# lav1n1a/plataforma-cursos-trilha architecture

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

- Interactive diagram: https://gitdiagram.com/lav1n1a/plataforma-cursos-trilha
- Repository: https://github.com/lav1n1a/plataforma-cursos-trilha

## Overview

Trilha is an in-development online course platform. The sampled runtime currently implements an OIDC-based login/session flow and user endpoints; the README describes course administration and participant capabilities, but the supplied tree shows no course, enrollment, lesson, progress, or certificate implementation. The web routes include login and empty admin/portal route declarations. Frontend-to-backend login wiring is not established by the excerpts, so that relationship is shown as unverified. The graph focuses on the implemented authentication workflow and marks documented course capabilities as planned.

Main entry points: [`backend/src/rotas/oidc.routes.ts`](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/rotas/oidc.routes.ts) (OIDC routes), [`backend/src/auth/users.ts`](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/auth/users.ts) (Identity resolution), [`backend/src/app.ts`](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/app.ts) (API app), [`backend/src/rotas/usuario.routes.ts`](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/rotas/usuario.routes.ts) (User routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_web_router["Web router<br/>[Router.tsx]"]
  node_login_page["Login page<br/>[page.tsx]"]
  node_login_form["Login form<br/>[login-form.tsx]"]
end

subgraph group_api["API runtime"]
  node_server["HTTP server<br/>[server.ts]"]
  node_app["API app<br/>[app.ts]"]
  node_oidc_routes["OIDC routes<br/>[oidc.routes.ts]"]
  node_user_routes["User routes<br/>[usuario.routes.ts]"]
end

subgraph group_identity["Identity and sessions"]
  node_oidc_protocol["OIDC protocol<br/>[exchange-code.ts]"]
  node_token_validation["Token validation"]
  node_session_guard["Session guard<br/>[require-session.ts]"]
  node_session_middleware["Session middleware<br/>[oidc-session.ts]"]
  node_session_store[("Session store<br/>[session-store.ts]")]
end

subgraph group_users["User management"]
  node_user_identity["Identity resolution<br/>[users.ts]"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
end

node_participant(("Participant"))
node_oidc_provider{{"OIDC provider"}}
node_course_admin["Course administration"]
node_participant_portal["Course participant portal"]

node_participant -->|"opens"| node_web_router
node_web_router -->|"routes to"| node_login_page
node_login_page -->|"renders"| node_login_form
node_login_form -.->|"login request"| node_oidc_routes
node_server -->|"mounts"| node_app
node_app -->|"mounts"| node_oidc_routes
node_app -->|"mounts"| node_user_routes
node_oidc_routes -->|"exchanges code"| node_oidc_protocol
node_oidc_routes -->|"validates token"| node_token_validation
node_oidc_routes -->|"saves session"| node_session_middleware
node_oidc_routes -->|"guards refresh"| node_session_guard
node_oidc_routes -->|"resolves identity"| node_user_identity
node_oidc_protocol -->|"exchanges tokens"| node_oidc_provider
node_token_validation -->|"loads discovery"| node_oidc_provider
node_session_guard -->|"loads user"| node_user_identity
node_user_routes -->|"requires session"| node_session_guard
node_user_routes -->|"lists users"| node_user_identity
node_session_store -->|"uses client"| node_prisma
node_user_identity -->|"queries users"| node_prisma
node_participant -.->|"planned access"| node_participant_portal
node_participant -.->|"planned management"| node_course_admin

click node_web_router "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/web/src/Router.tsx"
click node_login_page "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/web/src/login/page.tsx"
click node_login_form "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/web/src/login/components/login-form.tsx"
click node_server "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/server.ts"
click node_app "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/app.ts"
click node_oidc_routes "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/rotas/oidc.routes.ts"
click node_user_routes "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/rotas/usuario.routes.ts"
click node_oidc_protocol "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/oidc/exchange-code.ts"
click node_token_validation "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/oidc/validate-id-token.ts"
click node_session_guard "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/auth/require-session.ts"
click node_session_middleware "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/middlewares/oidc-session.ts"
click node_session_store "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/auth/session-store.ts"
click node_user_identity "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/auth/users.ts"
click node_prisma "https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/data/prisma.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_router,node_login_page,node_login_form toneBlue
class node_server,node_app,node_oidc_routes,node_user_routes toneAmber
class node_oidc_protocol,node_token_validation,node_session_guard,node_session_middleware,node_session_store toneMint
class node_user_identity,node_prisma toneRose
class node_participant,node_oidc_provider,node_course_admin,node_participant_portal toneIndigo
```

## Components

### Web interface

- [Web router](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/web/src/Router.tsx): `web/src/Router.tsx`
- [Login page](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/web/src/login/page.tsx): `web/src/login/page.tsx`
- [Login form](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/web/src/login/components/login-form.tsx): `web/src/login/components/login-form.tsx`

### API runtime

- [HTTP server](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/server.ts): `backend/src/server.ts`
- [API app](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/app.ts): `backend/src/app.ts`
- [OIDC routes](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/rotas/oidc.routes.ts): `backend/src/rotas/oidc.routes.ts`
- [User routes](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/rotas/usuario.routes.ts): `backend/src/rotas/usuario.routes.ts`

### Identity and sessions

- [OIDC protocol](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/oidc/exchange-code.ts): `backend/src/oidc/exchange-code.ts`
- [Token validation](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/oidc/validate-id-token.ts): `backend/src/oidc/validate-id-token.ts`
- [Session guard](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/auth/require-session.ts): `backend/src/auth/require-session.ts`
- [Session middleware](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/middlewares/oidc-session.ts): `backend/src/middlewares/oidc-session.ts`
- [Session store](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/auth/session-store.ts): `backend/src/auth/session-store.ts`

### User management

- [Identity resolution](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/auth/users.ts): `backend/src/auth/users.ts`
- [Prisma client](https://github.com/lav1n1a/plataforma-cursos-trilha/blob/master/backend/src/data/prisma.ts): `backend/src/data/prisma.ts`

### Other components

- **Participant**
- **OIDC provider**
- **Course administration**
- **Course participant portal**

## Connections

- Participant → Web router: opens (evidence: `web/src/Router.tsx`)
- Web router → Login page: routes to (evidence: `web/src/Router.tsx`)
- Login page → Login form: renders (evidence: `web/src/login/page.tsx`)
- Login form → OIDC routes: login request
- HTTP server → API app: mounts (evidence: `backend/src/server.ts`)
- API app → OIDC routes: mounts (evidence: `backend/src/app.ts`)
- API app → User routes: mounts (evidence: `backend/src/app.ts`)
- OIDC routes → OIDC protocol: exchanges code (evidence: `backend/src/rotas/oidc.routes.ts`)
- OIDC routes → Token validation: validates token (evidence: `backend/src/rotas/oidc.routes.ts`)
- OIDC routes → Session middleware: saves session (evidence: `backend/src/rotas/oidc.routes.ts`)
- OIDC routes → Session guard: guards refresh (evidence: `backend/src/rotas/oidc.routes.ts`)
- OIDC routes → Identity resolution: resolves identity (evidence: `backend/src/rotas/oidc.routes.ts`)
- OIDC protocol → OIDC provider: exchanges tokens (evidence: `backend/src/oidc/exchange-code.ts`)
- Token validation → OIDC provider: loads discovery (evidence: `backend/src/oidc/validate-id-token.ts`)
- Session guard → Identity resolution: loads user (evidence: `backend/src/auth/require-session.ts`)
- User routes → Session guard: requires session (evidence: `backend/src/rotas/usuario.routes.ts`)
- User routes → Identity resolution: lists users (evidence: `backend/src/rotas/usuario.routes.ts`)
- Session store → Prisma client: uses client (evidence: `backend/src/auth/session-store.ts`)
- Identity resolution → Prisma client: queries users (evidence: `backend/src/auth/users.ts`)
- Participant → Course participant portal: planned access (evidence: `README.md`)
- Participant → Course administration: planned management (evidence: `README.md`)
