docs: improve README

Co-authored-by: Claude <noreply@anthropic.com>

Author: FreekBes

README.md

@@ -1,68 +1,49 @@
 # Codam's Custom Coalition System
 
-A work in progress.
+The Codam Coalition System is a web application that manages student-coalition competition at Codam Coding College, part of the 42 Network. Students are sorted into teams (coalitions) and compete for points earned through their academic activity — projects, evaluations, logtime, events, and more. Points are awarded automatically via Intra webhooks and synchronized back to Intra.
 
-## To-do list
+It is a replacement for 42's existing coalition system, intending to make it more fair, engaging, and transparent for students while giving staff more control and flexibility in how the competition is structured.
 
-### Deployment
-- [x] Finalize containerization
-- [x] Switch to containerized postgres database
+## Features
 
-### Questionnaire
-- [x] Code questionnaire
-- [x] Code questionnaire results
-- [x] Only make questionnaire available between specific dates set by admin
-- [x] Allow users without an assigned coalition to always fill in the questionnaire
+- **Sorting Hat quiz** — students answer a weighted questionnaire to get placed into a coalition
+- **Points system** — automatic point awards for projects, exams, evaluations, logtime, and event organization
+- **Coalition leaderboard** — coalitions compete based on the mean score of their active contributors
+- **Individual rankings** — cross-coalition leaderboards measuring specific engagement types
+- **Titles** — top-ranked students receive titles that appear on their Intra profile
+- **Season history** — frozen snapshots of final standings at the end of each season
+- **Canvas displays** — server-rendered 1920×1080 PNG images with real-time colorful data for campus screens
+- **Admin interface for staff** — point management, quiz editor, webhook tools, and more
 
-### Points system & tournament
-- [x] Implement Codam's new point system
-- [x] Improve Codam's new point system (add custom project point system, rip out Intra's)
-- [x] Set up automated points system using Intra webhooks
-- [x] Implement Intra's bloc season system
-- [x] Implement a way of assigning bonus points to top ranking students in seasons
+## Documentation
 
-### Student interface
-- [x] Create basic dashboard
-- [x] Create basic graphs
-- [x] Create various rankings
-- [x] Create season history overview with historical wins
+Full documentation is in the [`docs/`](docs/) folder:
 
-### Admin / staff interface
-- [x] Create dashboard
-- [x] Create interface for editing the questionnaire
-- [x] Create interface to manually trigger webhooks (manually re-assign automated points)
-- [x] Create interface to fetch potentially missed webhooks between specific dates
-- [x] Create point history interface where admin can delete, recalculate and synchronize points with Intra
-- [x] Create interface to edit automated point system
-- [x] Implement method to recalculate already given points
-- [x] Create interface for manually assigning custom points
-- [x] Create interface for manually assigning points for organizing events
+| Section | Description |
+|---------|-------------|
+| [Architecture](docs/architecture.md) | Tech stack, directory structure, and database schema |
+| [Configuration](docs/configuration.md) | Environment variables and Docker setup |
+| [Development](docs/development.md) | Local setup, npm scripts, and dev utilities |
+| [Features](docs/features/coalitions.md) | Coalitions, scoring, quiz, rankings, titles, charts, canvas |
+| [Intra Sync](docs/sync/overview.md) | How and when data is synchronized with Intra |
+| [Webhooks](docs/sync/webhooks.md) | Webhook event handlers and the catchup tool |
+| [Admin Interface](docs/admin/overview.md) | Admin routes and tools |
 
-### Intra connection (API & Webhooks)
-- [x] Implement a way of synchronizing points with Intra
-- [x] Implement a way of averaging out the points on Intra
-- [ ] Implement a way of syncing existing Intra points including historical ones
-- [ ] Find a way of blocking Intra's coalitions_user creation
-- [x] Implement granting titles for top #1 of each ranking at the end of each season
-- [x] Re-implement old [coalition rank titles system](https://github.com/codam-coding-college/coalition-ranks)
+## Quick Start
 
-If you're a student and want to contribute to this project, talk to the staff about it first to figure out what is possible and discuss implementation ideas.
+See [docs/development.md](docs/development.md) for full setup instructions. In brief:
 
-## Development
-1. Clone the repository
-2. Fill the `.env` file with the necessary environment variables (don't forget to change the POSTGRES_HOST in the PRISMA_DB_URL variable to localhost)
-3. Run `npm install` to install dependencies
-4. Run `npm run build` to build the project
-5. Start the PostgreSQL database using Docker: `docker-compose -f docker-compose.dev.yml up -d`
-6. Run `npm run start` to start the server and seed the initial database
-7. Optional:
-	- run `node build/dev/create_quiz_questions.js` to seed the database with initial questionnaire questions
-	- run `node build/dev/create_rankings.js` to seed the database with initial rankings
-	- synchronize some data from Intra using the Webhook Catch-up tool in the Admin interface
+```bash
+cp .env.example .env          # fill in your Intra API credentials and database settings
+npm install
+docker compose -f docker-compose.dev.yml up -d   # start PostgreSQL
+npm run build && npm start
+```
 
-### Reseed the database
-1. Delete the *.sync-timestamp* file in the root directory
-2. Run `npm run build && npm run start`
+The application runs on port 4000. Access it at `http://localhost:4000`.
 
-### Add initial questionnaire questions
-Run `node build/dev/create_quiz_questions.js` after running `npm run build`
+## Contributing
+
+If you are a student and want to contribute, talk to the Codam staff first to discuss what is possible and to align on implementation ideas.
+
+If you are a staff member from another campus and want to set up a similar system, we recommend forking this repository and customizing it to your campus's needs. Feel free to reach out to the Codam staff for guidance on how to adapt the system to your context.

docs/development.md

@@ -34,7 +34,13 @@
    ```
    The application runs on port 4000 by default (`URL_ORIGIN` in `.env`).
 
-5. Access the application at `http://localhost:4000`.
+5. (optional) Run the following development scripts to seed the database with necessary data:
+   ```bash
+   node build/dev/create_quiz_questions.js # Seed the database with initial questionnaire questions and answers
+   node build/dev/create_rankings.js # Create initial cross-coalition ranking definitions
+   ```
+
+6. Access the application at `http://localhost:4000`. Optionally synchronize some recent data from Intra using the [webhook catch-up tool](admin/hooks-management.md#catchup-tool) to have a more complete local dataset with some scores and titles awarded locally.
 
 ## npm Scripts