# Database Documentation

Complete documentation for the Post-ERG thesis database.

## 📚 Available Documentation

### 1. **[DATABASE_SPECIFICATION.md](DATABASE_SPECIFICATION.md)** ⭐
**Complete technical specification** - 25KB comprehensive document

**Contents:**
- Complete table definitions with all columns
- Entity relationship diagrams
- Junction table specifications
- Lookup table values
- Business rules and workflows
- Sample queries and use cases
- Instructions for requesting schema changes

**Use when:** You need complete technical details about the database structure.

---

### 2. **[QUICK_SCHEMA_REFERENCE.md](QUICK_SCHEMA_REFERENCE.md)** 🚀
**Quick reference guide** - 5KB at-a-glance reference

**Contents:**
- Table summary
- Key relationships diagram
- Core fields reference
- Predefined lookup values
- Common SQL queries
- Constraint summary

**Use when:** You need quick lookup or common query examples.

---

### 3. **[schema.sql](schema.sql)** 💾
**The actual SQL schema** - Executable SQL file

**Contents:**
- Complete CREATE TABLE statements
- Indexes and triggers
- Predefined data (orientations, AP programs, etc.)
- Views for common queries

**Use when:** Setting up or resetting the database.

---

## 🚀 Quick Start

### View Database Schema
```bash
# Read the quick reference
cat database/QUICK_SCHEMA_REFERENCE.md

# Or full specification
cat database/DATABASE_SPECIFICATION.md
```

### Initialize Database
```bash
# Create test database from schema
just init-test-db

# Create with sample data
just create-fixtures
```

### Query Database
```bash
# Open SQLite prompt
just query-db

# Show specific thesis
just show-thesis 42
```

## 📝 Making Schema Changes

### Step 1: Document Your Request

Format:
```
**Table:** [table_name]
**Change Type:** [add/modify/remove]
**What:** [description]
**Why:** [reason/use case]
**Example Data:** [samples]
```

### Step 2: Specify Details

For **new columns**:
- Column name
- Data type (TEXT, INTEGER, BOOLEAN, DATETIME)
- NULL/NOT NULL
- Default value
- Indexes needed?

For **new tables**:
- Table name
- All columns
- Relationships to existing tables
- Sample data

### Step 3: Provide Context

Include:
- Use case scenario
- Who will use it?
- How will it be displayed?
- Any constraints?

### Example Request

```
**Table:** theses
**Change Type:** add column
**What:** Add column to track if thesis won an award
**Why:** Need to highlight award-winning theses on homepage
**Column Name:** has_award
**Data Type:** BOOLEAN
**Default:** 0 (false)
**Example:** 1 for "Prix du Jury 2025" winner
```

## 🗂️ Database Structure Overview

```
┌─────────────┐
│   theses    │ ◄── Main table (500+ records/year)
└──────┬──────┘
       │
       ├──► authors (via thesis_authors)
       ├──► supervisors (via thesis_supervisors)
       ├──► keywords (via thesis_keywords)
       ├──► languages (via thesis_languages)
       ├──► formats (via thesis_formats)
       ├──► thesis_files (attachments)
       │
       └──► Lookup tables:
            • orientations
            • ap_programs
            • finality_types
            • access_types
            • license_types
```

## 📊 Key Statistics

- **Core tables:** 3 (theses, authors, supervisors)
- **Junction tables:** 5 (many-to-many relationships)
- **Lookup tables:** 7 (predefined values)
- **Support tables:** 2 (files, pages)
- **Views:** 2 (full data, public only)
- **Indexes:** 11 (for performance)
- **Triggers:** 4 (auto-update timestamps)

## 🔍 Common Scenarios

### Scenario 1: Student Submits Thesis
1. Create record in `theses` (is_published=0)
2. Add author to `authors`, link via `thesis_authors`
3. Add supervisor(s) to `supervisors`, link via `thesis_supervisors`
4. Set `orientation_id`, `ap_program_id`, `finality_id`
5. Upload file to `thesis_files`
6. Add keywords via `thesis_keywords`
7. Set `submitted_at` timestamp

### Scenario 2: Admin Publishes Thesis
1. Verify all required fields present
2. Set `defense_date`
3. Set `jury_points`
4. Optional: add `context_note`
5. Set `is_published = 1`
6. Set `published_at = CURRENT_TIMESTAMP`

### Scenario 3: Public User Searches
Query `v_theses_public` view with filters:
- By year
- By orientation
- By keyword
- By author name
- Full-text search in title/synopsis

## 🛠️ Development Workflow

### Local Development
1. Use `xamxam.db` for development
2. Create via `just init-db`
3. Test queries before deployment

## 📞 Need Help?

1. **Quick lookup** → Read `QUICK_SCHEMA_REFERENCE.md`
2. **Complete details** → Read `DATABASE_SPECIFICATION.md`
3. **Schema changes** → Follow format in this README
4. **SQL examples** → Check `QUICK_SCHEMA_REFERENCE.md`

## 🔗 Related Documentation

- [Deployment Guide](../nginx/DEPLOYMENT_COMPLETE.md)
- [Repository Structure](../REPOSITORY_STRUCTURE_ANALYSIS.md)
- [Test Database Guide](../nginx/TEST_DATABASE_SETUP.md)