PolyMPR/CLAUDE.md

PolyMPR - Claude Code Context

📋 Project Overview

PolyMPR (Poly Management Platform for Resources) is a modular HR management system built with Deno + Fresh framework. It's designed to help organizations manage HR, student records, notes, mobility programs, and role-based administration.

Stack

• Runtime: Deno
• Framework: Fresh (edge-ready web framework)
• Database: PostgreSQL with Drizzle ORM
• Frontend: Preact with signals
• Authentication: JWT-based via cookies
• Testing: Deno test framework with HappyDOM for DOM testing

Current Status

🚧 In Progress - API layer largely complete, UI pages not yet built. The schema below is the final/definitive schema that guides all development.

---

🏗️ Architecture

Module Structure

The application uses a modulith architecture with the following modules:

routes/(apps)/
├── students/      - Student management & promotions
├── notes/         - Grade management & academic records
├── mobility/      - Mobility programs & exchanges
└── admin/         - Role & permission management

Key Directories

• /routes - Fresh routes and components
• /databases - Database connection, schema, and migrations
• /defaults - Interfaces and shared types
• /tests - Unit, integration, and E2E tests
• /static - Public assets

Authentication Flow

1. User authenticates via CAS (Polytech)
2. JWT token stored in sessionToken cookie
3. Middleware validates token on each request
4. Public routes: /, /login, /logout, /about, /contact
5. All other routes require authentication

---

📊 Database Schema (Final/Definitive)

erDiagram
  USER {
    string id PK
    string nom
    string prenom
    int idRole FK
  }
  ROLE {
    int id PK
    string nom
  }
  PERMISSION {
    int id PK
    string nom
  }
  ROLE_PERMISSION {
    int idRole PK,FK
    int idPermission PK,FK
  }
  STUDENT {
    int numEtud PK
    string nom
    string prenom
    string idPromo FK
  }
  PROMOTION {
    string idPromo PK
    string annee
  }
  MODULE {
    string id PK
    string nom
  }
  ENSEIGNEMENT {
    string idProf PK,FK
    string idModule PK,FK
    string idPromo PK,FK
  }
  UE {
    int id PK
    string nom
  }
  UE_MODULE {
    string idModule PK,FK
    int idUE PK,FK
    string idPromo PK,FK
    float coeff
  }
  NOTE {
    int numEtud PK,FK
    string idModule PK,FK
    float note
  }
  AJUSTEMENT {
    int numEtud PK,FK
    int idUE PK,FK
    float valeur
  }

  USER }o--|| ROLE : "a"
  ROLE_PERMISSION }o--|| ROLE : "accorde"
  ROLE_PERMISSION }o--|| PERMISSION : "inclut"
  ENSEIGNEMENT }o--|| USER : "réalisé par"
  ENSEIGNEMENT }o--|| MODULE : "porte sur"
  ENSEIGNEMENT }o--|| PROMOTION : "concerne"
  STUDENT }o--|| PROMOTION : "appartient à"
  UE_MODULE }o--|| MODULE : "associe"
  UE_MODULE }o--|| UE : "appartient à"
  UE_MODULE }o--|| PROMOTION : "pour"
  NOTE }o--|| STUDENT : "reçoit"
  NOTE }o--|| MODULE : "dans"
  AJUSTEMENT }o--|| STUDENT : "concerne"
  AJUSTEMENT }o--|| UE : "dans"

Current Schema

The Drizzle ORM schema in /databases/schema.ts implements all tables: roles, permissions, rolePermissions, users, promotions, students, modules, enseignements, ues, ueModules, notes, ajustements, mobility.

---

🎯 Open Issues (69 total)

UI Pages

Catalog

• 📋 UI - Page Catalogue d'applications (#71)

Components

• 🎨 UI (composant) - Popup Résultats d'import (#75)

Students

• 📋 UI - Admin – Liste des élèves (#79)
• 📋 UI - Admin – Gestion des promotions (#80)
• 📋 UI - Admin – Import xlsx élèves (#81)
• 📋 UI - Admin – Édition d'un élève (#82)

Notes

• 📋 UI - Page Élève – Mes Notes (#72)
• 📋 UI - Admin – Consulter les notes (#73)
• 📋 UI - Admin – Importer des notes (.xlsx) (#74)
• 📋 UI - Admin – Édition notes d'un élève (#76)
• 📋 UI - Admin – Récap notes élève / semestre (#77)
• 📋 UI - Admin – Gestion des UEs (#78)

Administration

• 📋 UI - Gestion des utilisateurs (#83)
• 📋 UI - Gestion des rôles (#84)
• 📋 UI - Permissions d'un rôle (#85)
• 📋 UI - Vue des permissions (#86)
• 📋 UI - Gestion des modules (#87)
• 📋 UI - Enseignements (Assignations) (#88)

---

API Endpoints

Legend: ✅ implemented & tested | 📋 not yet implemented

Students API

• ✅ GET /students (#7)
• ✅ POST /students (#8)
• ✅ POST /students/import-csv (#9)
• ✅ GET /students/{numEtud} (#10)
• ✅ PUT /students/{numEtud} (#11)
• ✅ DELETE /students/{numEtud} (#12)
• ✅ GET /promotions (#13)
• ✅ POST /promotions (#14)
• ✅ GET /promotions/{idPromo} (#15)
• ✅ PUT /promotions/{idPromo} (#16)
• ✅ DELETE /promotions/{idPromo} (#17)

Administration API - Modules & Enseignements

• ✅ GET /modules (#23)
• ✅ POST /modules (#24)
• ✅ GET /modules/{idModule} (#25)
• ✅ PUT /modules/{idModule} (#26)
• ✅ DELETE /modules/{idModule} (#27)
• ✅ POST /enseignements (#29)
• ✅ GET /enseignements/{idProf}/{idModule}/{idPromo} (#30)
• ✅ DELETE /enseignements/{idProf}/{idModule}/{idPromo} (#31)

Notes API - UEs & UE-Modules

• ✅ GET /ues (#32)
• ✅ POST /ues (#33)
• ✅ GET /ues/{idUE} (#34)
• ✅ PUT /ues/{idUE} (#35)
• ✅ DELETE /ues/{idUE} (#36)
• ✅ GET /ue-modules (#37)
• ✅ POST /ue-modules (#38)
• ✅ GET /ue-modules/{idModule}/{idUE}/{idPromo} (#39)
• ✅ PUT /ue-modules/{idModule}/{idUE}/{idPromo} (#40)
• ✅ DELETE /ue-modules/{idModule}/{idUE}/{idPromo} (#41)

Notes API - Notes & Ajustements

• ✅ GET /notes (#42)
• ✅ POST /notes (#43)
• 📋 POST /notes/import-xlsx (#44)
• ✅ GET /notes/{numEtud}/{idModule} (#45)
• ✅ PUT /notes/{numEtud}/{idModule} (#46)
• ✅ DELETE /notes/{numEtud}/{idModule} (#47)
• ✅ GET /ajustements (#48)
• ✅ POST /ajustements (#49)
• ✅ GET /ajustements/{numEtud}/{idUE} (#50)
• ✅ PUT /ajustements/{numEtud}/{idUE} (#51)
• ✅ DELETE /ajustements/{numEtud}/{idUE} (#52)

Administration API - Users, Roles & Permissions

• ✅ GET /users (#60)
• ✅ POST /users (#61)
• ✅ GET /users/{id} (#62)
• ✅ PUT /users/{id} (#63)
• ✅ DELETE /users/{id} (#64)
• ✅ GET /roles (#65)
• ✅ POST /roles (#66)
• ✅ GET /roles/{idRole} (#67)
• ✅ PUT /roles/{idRole} (#68)
• ✅ DELETE /roles/{idRole} (#69)
• ✅ GET /permissions (#70)

---

🎨 Design Reference

Figma Prototype: https://www.figma.com/design/La79bsUsWnJCtMsrrt2zGd/Prototype?node-id=0-1

This is the final design specification for the UI. All UI implementations should follow this design.

---

🚀 Development Guidelines

Getting Started

# Run tests
deno task test

# Start development server
deno task start

# Build for production
deno task build

# Format & lint
deno task check

Git Workflow

1. Create branch: git checkout -b PMPR-{ISSUE_ID}
2. Implement changes
3. Run tests and linting
4. Submit PR

Code Style

• Format: Follow Deno defaults (enforced via deno fmt)
• Linting: Fresh recommended rules
• TypeScript strict mode enabled
• Use Drizzle ORM for database operations

Testing

3-level architecture — all 149 tests pass:

• Unit (tests/unit/) — pure logic with mock DB + mock API, no real DB
• Integration (tests/integration/) — Drizzle ORM direct on real DB
• E2E (tests/e2e/) — Fresh handler + real DB (handler-level, not browser)

Helpers in tests/helpers/:

• handler.ts — builds fake Fresh contexts (makeEmployeeContext, makeJsonRequest…)
• db_integration.ts — seed functions + truncateAll() for test isolation
• db_mock.ts / api_mock.ts — in-memory mocks for unit tests

deno task test                  # run all tests
deno task test:coverage         # coverage report (terminal)
deno task test:coverage:html    # coverage report (HTML → coverage/html/index.html)
nix run nixpkgs#act -- -j unit --no-cache-server        # unit tests via GitHub Actions
nix run nixpkgs#act -- -j integration --no-cache-server # integration + e2e via GitHub Actions

---

📦 Key Dependencies

• fresh@1.7.3 - Web framework
• drizzle-orm@0.45.2 - ORM
• pg@8.20.0 - PostgreSQL driver
• @popov/jwt@1.0.1 - JWT utilities
• preact@10.22.0 - UI library
• happy-dom@16.0.0 - DOM testing

---

🔗 Related Resources

• Repository: https://git.polytech.djalim.fr/djalim/PolyMPR
• Issue Tracker: Gitea (via tea CLI)
• Wiki: Check CONTRIBUTING.md for dev setup
• Database: PostgreSQL (configured in .env)

---

💡 Important Notes

1. Only missing API: POST /notes/import-xlsx (#44) — all other endpoints are implemented.
2. Next priority: UI pages (none built yet) — follow the Figma prototype.
3. Module Pattern: Each module should follow the same pattern: routes, API endpoints, components, and tests.
4. Permissions: All admin operations should respect the ROLE_PERMISSION system.
5. Fresh Conventions: Routes use Fresh's file-based routing convention (e.g., routes/path/index.tsx).
6. Drizzle .where() pitfall: Always wrap multiple conditions with and(). .where(eq(a), eq(b)) silently ignores the second argument.