xamxam/docs/QUICK_SCHEMA_REFERENCE.md

# Database Quick Reference

Quick lookup for the Post-ERG database schema.

## 📊 Table Summary

| Table | Type | Records | Description |
|-------|------|---------|-------------|
| `theses` | Core | ~500/year | Main thesis records |
| `authors` | Core | ~600 | Student/author info |
| `supervisors` | Core | ~50 | Thesis supervisors |
| `thesis_authors` | Junction | ~550/year | Thesis ↔ Authors |
| `thesis_supervisors` | Junction | ~600/year | Thesis ↔ Supervisors |
| `thesis_languages` | Junction | ~550/year | Thesis ↔ Languages |
| `thesis_formats` | Junction | ~700/year | Thesis ↔ Formats |
| `thesis_keywords` | Junction | ~3000/year | Thesis ↔ Keywords |
| `thesis_files` | Support | ~800/year | File attachments |
| `orientations` | Lookup | 15 | Art orientations |
| `ap_programs` | Lookup | 4 | Workshop programs |
| `finality_types` | Lookup | 3 | Master finalities |
| `languages` | Lookup | 2+ | Languages |
| `format_types` | Lookup | 7 | Media formats |
| `access_types` | Lookup | 3 | Access levels |
| `license_types` | Lookup | ~10 | Creative Commons |
| `keywords` | Lookup | ~500+ | Tag system |
| `pages` | Support | 4 | Static pages |

## 🔑 Key Relationships

```
theses ──┬── 1:N ──► thesis_authors ──► N:1 ── authors
         ├── 1:N ──► thesis_supervisors ──► N:1 ── supervisors
         ├── 1:N ──► thesis_keywords ──► N:1 ── keywords
         ├── 1:N ──► thesis_languages ──► N:1 ── languages
         ├── 1:N ──► thesis_formats ──► N:1 ── format_types
         ├── 1:N ──► thesis_files
         ├── N:1 ──► orientations
         ├── N:1 ──► ap_programs
         ├── N:1 ──► finality_types
         ├── N:1 ──► access_types
         └── N:1 ──► license_types
```

## 📝 Core Fields Reference

### `theses` (Main Table)

**Identity:**
- `id` - Primary key
- `identifier` - Human-readable ID (e.g., "2025-002")

**Basic Info:**
- `title` - Thesis title (required)
- `subtitle` - Optional subtitle
- `year` - Academic year (required)
- `is_doctoral` - TFE (0) or Doctoral (1)

**Academic:**
- `orientation_id` - Art orientation
- `ap_program_id` - Workshop program
- `finality_id` - Master finality type

**Content:**
- `synopsis` - ~200 word summary
- `context_note` - Jury note (max 150 words)
- `duration_minutes` - For audio/video
- `duration_pages` - For written works

**Access:**
- `access_type_id` - Public/Internal/Restricted
- `license_id` - Creative Commons, etc.

**Workflow:**
- `submitted_at` - Student submission
- `defense_date` - Defense date
- `is_published` - Public visibility
- `published_at` - Publication date
- `jury_points` - Grade (0-20)

## 🏷️ Lookup Values

### Orientations (15)
Arts Numériques, Dessin, Cinéma d'animation, Installation-Performance, Peinture, Photographie, Sculpture, Vidéographie, Graphisme, Typographie, Design Numérique, Illustration, Bande-Dessinée, Sérigraphie, Gravure

### AP Programs (4)
- Narration Spéculative
- Design et Politique du Multiple (DPM)
- Atelier Pratiques Situées (APS)
- Lieux, Interdisciplinarités, Écologie, Nécessité, Systèmes (LIENS)

### Finality Types (3)
Approfondi, Enseignement, Spécialisé

### Languages (2+)
Français, Anglais

### Format Types (7)
Site web, Audio, Vidéo, Performance, Objet éditorial, Installation, Autre

### Access Types (3)
- **Libre**: Full access online + library
- **Interne**: Library only, note online
- **Interdit**: No access, note only

## 🔍 Common Queries

### Get Published Theses
```sql
SELECT * FROM v_theses_public ORDER BY year DESC;
```

### Get Thesis by ID
```sql
SELECT * FROM v_theses_full WHERE id = ?;
```

### Search by Title
```sql
SELECT * FROM v_theses_public 
WHERE title LIKE '%keyword%' 
ORDER BY year DESC;
```

### Filter by Year
```sql
SELECT * FROM v_theses_public 
WHERE year = 2025 
ORDER BY title;
```

### Filter by Orientation
```sql
SELECT t.* FROM theses t
JOIN orientations o ON t.orientation_id = o.id
WHERE o.name = 'Arts Numériques'
AND t.is_published = 1;
```

### Get Author's Theses
```sql
SELECT t.* FROM theses t
JOIN thesis_authors ta ON t.id = ta.thesis_id
JOIN authors a ON ta.author_id = a.id
WHERE a.name LIKE '%name%'
AND t.is_published = 1;
```

### Get Keywords for Thesis
```sql
SELECT k.keyword FROM keywords k
JOIN thesis_keywords tk ON k.id = tk.keyword_id
WHERE tk.thesis_id = ?;
```

### Count by Year
```sql
SELECT year, COUNT(*) as count
FROM theses
WHERE is_published = 1
GROUP BY year
ORDER BY year DESC;
```

## 📌 Important Constraints

- **Unique:** `theses.identifier`, `authors.email`, all lookup table names
- **Required:** `theses.title`, `theses.year`, at least one author
- **Max:** 10 keywords per thesis
- **Range:** `jury_points` 0.00 - 20.00
- **Cascade:** All junction tables DELETE CASCADE

## 🎯 Views

### `v_theses_full`
Complete thesis data with all relationships (comma-separated).

### `v_theses_public`  
Only published theses (`is_published = 1`).

## 🔧 Making Changes

**Format for change requests:**

```
Table: [table_name]
Change: [add/modify/remove]
Column: [column_name]
Type: [data_type]
Reason: [why needed]
Example: [sample data]
```

**Example:**

```
Table: theses
Change: add
Column: external_url
Type: TEXT
Reason: Link to external project website
Example: https://example.com/project
```

## 📚 Full Documentation

See `DATABASE_SPECIFICATION.md` for complete details.