# 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)

```mermaid
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

```bash
# 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

```bash
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.