# lord-melflam/studens architecture

> Architecture diagram of the GitHub repository lord-melflam/studens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lord-melflam/studens
- Repository: https://github.com/lord-melflam/studens

## Overview

Studens is a modular student platform; its deployed module is RYC, a course catalogue and review service. The main journey runs from public pages and sign-in through first-run setup into the app shell, where students browse institution-scoped catalogues, read course details and submit or read reviews. Catalogue data is crawled from university sources, parsed into snapshots and exposed through a read interface. Other product branches include account management, moderation, feedback and suspension handling. Relationships beyond the excerpts are included only where the README or source index documents them; unsampled implementation details are not assumed.

Main entry points: [`apps/web/src/main.tsx`](https://github.com/lord-melflam/studens/blob/main/apps/web/src/main.tsx) (Web entry and zones), [`apps/api/src/routes/auth.ts`](https://github.com/lord-melflam/studens/blob/main/apps/api/src/routes/auth.ts) (Sign-in routes), [`packages/ryc-ui/src`](https://github.com/lord-melflam/studens/tree/main/packages/ryc-ui/src) (RYC screens), [`apps/web/src/moderation/Console.tsx`](https://github.com/lord-melflam/studens/blob/main/apps/web/src/moderation/Console.tsx) (Moderation console and API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_entry["Web entry and zones<br/>[main.tsx]"]
  node_routing["Language routing<br/>[router.ts]"]
  node_public["Public site"]
  node_first_run["First-run setup"]
  node_app_shell["App shell and modules"]
end

subgraph group_identity["Identity and accounts"]
  node_auth_routes["Sign-in routes<br/>[auth.ts]"]
  node_identity["Identity resolution<br/>[identity.ts]"]
  node_session["Session lifecycle<br/>[session.ts]"]
  node_cookie["Session cookies<br/>[cookies.ts]"]
  node_account_routes["Account features<br/>[account.ts]"]
end

subgraph group_ryc["RYC catalogue and reviews"]
  node_ryc_ui["RYC screens"]
  node_ryc_api["RYC API<br/>[reviews.ts]"]
  node_ryc_domain["Review operations"]
  node_catalogue_read["Catalogue read interface<br/>[read.ts]"]
end

subgraph group_operations["Trust and operations"]
  node_moderation["Moderation console and API<br/>[Console.tsx]"]
  node_feedback["Feedback handling<br/>[feedback.ts]"]
  node_suspension["Suspension notices<br/>[suspension.ts]"]
  node_mail_worker["Mail delivery worker<br/>[send-mail.ts]"]
end

subgraph group_catalogue["Catalogue ingestion"]
  node_catalogue_worker["Catalogue ingestion worker"]
  node_source_crawlers["Institution crawlers"]
  node_ulb_parsers["ULB source parsers"]
  node_course_parser["Course-page parser<br/>[offering.ts]"]
  node_snapshot["Snapshot validation and storage<br/>[snapshot.ts]"]
end

node_visitor(("Visitor or student"))

node_visitor -->|"opens site"| node_web_entry
node_web_entry -->|"resolves route"| node_routing
node_web_entry -->|"renders public zone"| node_public
node_web_entry -->|"routes first run"| node_first_run
node_web_entry -->|"renders app"| node_app_shell
node_visitor -->|"signs in"| node_auth_routes
node_auth_routes -->|"resolves identity"| node_identity
node_auth_routes -->|"sets auth cookie"| node_cookie
node_identity -->|"checks session"| node_session
node_visitor -->|"uses modules"| node_app_shell
node_app_shell -->|"mounts module"| node_ryc_ui
node_ryc_ui -->|"requests reviews"| node_ryc_api
node_ryc_api -->|"delegates review edits"| node_ryc_domain
node_ryc_ui -.->|"browses courses"| node_catalogue_read
node_catalogue_worker -->|"runs crawls"| node_source_crawlers
node_source_crawlers -->|"parses ULB pages"| node_ulb_parsers
node_source_crawlers -.->|"parses offerings"| node_course_parser
node_catalogue_worker -.->|"loads snapshots"| node_snapshot
node_catalogue_read -->|"reads snapshots"| node_snapshot
node_visitor -->|"manages account"| node_account_routes
node_visitor -->|"reports content"| node_moderation
node_moderation -.->|"reviews feedback"| node_feedback
node_moderation -.->|"decides suspensions"| node_suspension
node_suspension -.->|"queues notice"| node_mail_worker

click node_web_entry "https://github.com/lord-melflam/studens/blob/main/apps/web/src/main.tsx"
click node_routing "https://github.com/lord-melflam/studens/blob/main/apps/web/src/router.ts"
click node_public "https://github.com/lord-melflam/studens/tree/main/apps/web/src/public"
click node_first_run "https://github.com/lord-melflam/studens/tree/main/apps/web/src/firstrun"
click node_app_shell "https://github.com/lord-melflam/studens/tree/main/apps/web/src/shell"
click node_ryc_ui "https://github.com/lord-melflam/studens/tree/main/packages/ryc-ui/src"
click node_ryc_api "https://github.com/lord-melflam/studens/blob/main/apps/api/src/routes/reviews.ts"
click node_ryc_domain "https://github.com/lord-melflam/studens/tree/main/packages/ryc/src"
click node_catalogue_read "https://github.com/lord-melflam/studens/blob/main/packages/ref/src/read.ts"
click node_auth_routes "https://github.com/lord-melflam/studens/blob/main/apps/api/src/routes/auth.ts"
click node_identity "https://github.com/lord-melflam/studens/blob/main/apps/api/src/identity.ts"
click node_session "https://github.com/lord-melflam/studens/blob/main/packages/platform/src/session.ts"
click node_cookie "https://github.com/lord-melflam/studens/blob/main/apps/api/src/cookies.ts"
click node_account_routes "https://github.com/lord-melflam/studens/blob/main/apps/api/src/routes/account.ts"
click node_moderation "https://github.com/lord-melflam/studens/blob/main/apps/web/src/moderation/Console.tsx"
click node_feedback "https://github.com/lord-melflam/studens/blob/main/packages/platform/src/feedback.ts"
click node_suspension "https://github.com/lord-melflam/studens/blob/main/packages/platform/src/suspension.ts"
click node_catalogue_worker "https://github.com/lord-melflam/studens/blob/main/apps/worker/src/ingest-catalogue.ts"
click node_source_crawlers "https://github.com/lord-melflam/studens/tree/main/packages/ref/src/sources"
click node_ulb_parsers "https://github.com/lord-melflam/studens/tree/main/packages/ref/src/sources/ulb"
click node_course_parser "https://github.com/lord-melflam/studens/blob/main/packages/ref/src/ingestion/parse/offering.ts"
click node_snapshot "https://github.com/lord-melflam/studens/blob/main/packages/ref/src/ingestion/snapshot.ts"
click node_mail_worker "https://github.com/lord-melflam/studens/blob/main/apps/worker/src/send-mail.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_entry,node_routing,node_public,node_first_run,node_app_shell toneBlue
class node_auth_routes,node_identity,node_session,node_cookie,node_account_routes toneAmber
class node_ryc_ui,node_ryc_api,node_ryc_domain,node_catalogue_read toneMint
class node_moderation,node_feedback,node_suspension,node_mail_worker toneRose
class node_catalogue_worker,node_source_crawlers,node_ulb_parsers,node_course_parser,node_snapshot,node_visitor toneIndigo
```

## Components

### Web experience

- [Web entry and zones](https://github.com/lord-melflam/studens/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Language routing](https://github.com/lord-melflam/studens/blob/main/apps/web/src/router.ts): `apps/web/src/router.ts`
- [Public site](https://github.com/lord-melflam/studens/tree/main/apps/web/src/public): `apps/web/src/public`
- [First-run setup](https://github.com/lord-melflam/studens/tree/main/apps/web/src/firstrun): `apps/web/src/firstrun`
- [App shell and modules](https://github.com/lord-melflam/studens/tree/main/apps/web/src/shell): `apps/web/src/shell`

### Identity and accounts

- [Sign-in routes](https://github.com/lord-melflam/studens/blob/main/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Identity resolution](https://github.com/lord-melflam/studens/blob/main/apps/api/src/identity.ts): `apps/api/src/identity.ts`
- [Session lifecycle](https://github.com/lord-melflam/studens/blob/main/packages/platform/src/session.ts): `packages/platform/src/session.ts`
- [Session cookies](https://github.com/lord-melflam/studens/blob/main/apps/api/src/cookies.ts): `apps/api/src/cookies.ts`
- [Account features](https://github.com/lord-melflam/studens/blob/main/apps/api/src/routes/account.ts): `apps/api/src/routes/account.ts`

### RYC catalogue and reviews

- [RYC screens](https://github.com/lord-melflam/studens/tree/main/packages/ryc-ui/src): `packages/ryc-ui/src`
- [RYC API](https://github.com/lord-melflam/studens/blob/main/apps/api/src/routes/reviews.ts): `apps/api/src/routes/reviews.ts`
- [Review operations](https://github.com/lord-melflam/studens/tree/main/packages/ryc/src): `packages/ryc/src`
- [Catalogue read interface](https://github.com/lord-melflam/studens/blob/main/packages/ref/src/read.ts): `packages/ref/src/read.ts`

### Trust and operations

- [Moderation console and API](https://github.com/lord-melflam/studens/blob/main/apps/web/src/moderation/Console.tsx): `apps/web/src/moderation/Console.tsx`
- [Feedback handling](https://github.com/lord-melflam/studens/blob/main/packages/platform/src/feedback.ts): `packages/platform/src/feedback.ts`
- [Suspension notices](https://github.com/lord-melflam/studens/blob/main/packages/platform/src/suspension.ts): `packages/platform/src/suspension.ts`
- [Mail delivery worker](https://github.com/lord-melflam/studens/blob/main/apps/worker/src/send-mail.ts): `apps/worker/src/send-mail.ts`

### Catalogue ingestion

- [Catalogue ingestion worker](https://github.com/lord-melflam/studens/blob/main/apps/worker/src/ingest-catalogue.ts): `apps/worker/src/ingest-catalogue.ts`
- [Institution crawlers](https://github.com/lord-melflam/studens/tree/main/packages/ref/src/sources): `packages/ref/src/sources`
- [ULB source parsers](https://github.com/lord-melflam/studens/tree/main/packages/ref/src/sources/ulb): `packages/ref/src/sources/ulb`
- [Course-page parser](https://github.com/lord-melflam/studens/blob/main/packages/ref/src/ingestion/parse/offering.ts): `packages/ref/src/ingestion/parse/offering.ts`
- [Snapshot validation and storage](https://github.com/lord-melflam/studens/blob/main/packages/ref/src/ingestion/snapshot.ts): `packages/ref/src/ingestion/snapshot.ts`

### Other components

- **Visitor or student**

## Connections

- Visitor or student → Web entry and zones: opens site (evidence: `apps/web/src/main.tsx`)
- Web entry and zones → Language routing: resolves route (evidence: `apps/web/src/main.tsx`)
- Web entry and zones → Public site: renders public zone (evidence: `apps/web/src/main.tsx`)
- Web entry and zones → First-run setup: routes first run (evidence: `apps/web/src/main.tsx`)
- Web entry and zones → App shell and modules: renders app (evidence: `apps/web/src/main.tsx`)
- Visitor or student → Sign-in routes: signs in
- Sign-in routes → Identity resolution: resolves identity (evidence: `apps/api/src/routes/auth.ts`)
- Sign-in routes → Session cookies: sets auth cookie (evidence: `apps/api/src/routes/auth.ts`)
- Identity resolution → Session lifecycle: checks session (evidence: `apps/api/src/identity.ts`)
- Visitor or student → App shell and modules: uses modules
- App shell and modules → RYC screens: mounts module
- RYC screens → RYC API: requests reviews (evidence: `packages/ryc-ui/src/api.ts`)
- RYC API → Review operations: delegates review edits (evidence: `apps/api/src/routes/reviews.ts`)
- RYC screens → Catalogue read interface: browses courses
- Catalogue ingestion worker → Institution crawlers: runs crawls (evidence: `apps/worker/src/ingest-catalogue.ts`)
- Institution crawlers → ULB source parsers: parses ULB pages (evidence: `packages/ref/src/sources/ulb/index.ts`)
- Institution crawlers → Course-page parser: parses offerings (evidence: `packages/ref/src/sources/ulb/index.ts`)
- Catalogue ingestion worker → Snapshot validation and storage: loads snapshots
- Catalogue read interface → Snapshot validation and storage: reads snapshots (evidence: `packages/ref/src/read.ts`)
- Visitor or student → Account features: manages account
- Visitor or student → Moderation console and API: reports content
- Moderation console and API → Feedback handling: reviews feedback
- Moderation console and API → Suspension notices: decides suspensions
- Suspension notices → Mail delivery worker: queues notice
