@@ -1,354 +0,0 @@
# 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 – #79 )
- 📋 UI - Admin – #80 )
- 📋 UI - Admin – #81 )
- 📋 UI - Admin – #82 )
**Notes **
- 📋 UI - Page Élève – #72 )
- 📋 UI - Admin – #73 )
- 📋 UI - Admin – #74 )
- 📋 UI - Admin – #76 )
- 📋 UI - Admin – #77 )
- 📋 UI - Admin – #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.