xamxam/app/storage

Database Documentation

Complete documentation for the XAMXAM thesis database.

📚 Available Documentation

1. 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 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 💾

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

# Read the quick reference
cat database/QUICK_SCHEMA_REFERENCE.md

# Or full specification
cat database/DATABASE_SPECIFICATION.md

Initialize Database

# Create test database from schema
just init-test-db

# Create with sample data
just create-fixtures

Query Database

# 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
• Repository Structure
• Test Database Guide