# thamesblanq/ulads-back architecture

> Architecture diagram of the GitHub repository thamesblanq/ulads-back, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thamesblanq/ulads-back
- Repository: https://github.com/thamesblanq/ulads-back

## Overview

ULADS Backend API serves student accounts and platform features through a NestJS HTTP/WebSocket backend. The main workflow is a client request entering a feature controller, passing through its service, and returning a result; authentication also consults user records and issues JWTs. Separate feature areas cover elections and voting, announcements and approval, academic resources, chat, and administrative audit logs. The README documents password recovery and centralized error handling; the sampled auth service shows database and email interactions, while wiring for other feature services is not sampled.

Main entry points: [`src/auth/jwt-auth.guard.ts`](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/jwt-auth.guard.ts) (JWT guard), [`src/auth/guards/roles.guard.ts`](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/guards/roles.guard.ts) (Roles guard), [`src/auth/auth.service.ts`](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/auth.service.ts) (Auth service), [`src/users/users.controller.ts`](https://github.com/thamesblanq/ulads-back/blob/main/src/users/users.controller.ts) (User routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity & Access"]
  node_auth_controller["Auth routes<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_users_controller["User routes"]
  node_users_service["Users service<br/>[users.service.ts]"]
  node_jwt_guard["JWT guard<br/>[jwt-auth.guard.ts]"]
  node_jwt_strategy["JWT strategy<br/>[jwt.strategy.ts]"]
  node_roles_guard["Roles guard<br/>[roles.guard.ts]"]
end

subgraph group_community["Member Features"]
  node_announcements_controller["Announcement routes"]
  node_announcements_service["Announcements service"]
  node_resources_controller["Resource routes"]
  node_resources_service["Resources service"]
  node_chat_gateway["Realtime chat<br/>[chat.gateway.ts]"]
end

subgraph group_governance["Elections &amp; Oversight"]
  node_elections_controller["Election routes"]
  node_elections_service["Elections service"]
  node_logs_controller["Audit log routes<br/>[logs.controller.ts]"]
  node_logs_service["Logs service<br/>[logs.service.ts]"]
end

subgraph group_runtime["API Runtime"]
  node_postgres[("PostgreSQL<br/>[database.ts]")]
  node_main["Nest bootstrap<br/>[main.ts]"]
  node_exceptions["Error filter"]
  node_logging["Request logging"]
  node_app_module["Application modules<br/>[app.module.ts]"]
end

node_client(("Platform client"))
node_mail["SMTP email"]

node_client -->|"sends auth requests"| node_auth_controller
node_client -->|"manages accounts"| node_users_controller
node_client -->|"uses announcements"| node_announcements_controller
node_client -->|"browses resources"| node_resources_controller
node_client -->|"votes and views"| node_elections_controller
node_client -->|"requests audit logs"| node_logs_controller
node_client -->|"opens chat"| node_chat_gateway
node_auth_controller -->|"delegates auth"| node_auth_service
node_auth_service -->|"looks up users"| node_users_service
node_auth_service -->|"reads and updates"| node_postgres
node_auth_service -->|"sends reset email"| node_mail
node_users_controller -->|"delegates account actions"| node_users_service
node_announcements_controller -->|"delegates announcements"| node_announcements_service
node_resources_controller -->|"delegates resources"| node_resources_service
node_elections_controller -->|"delegates election actions"| node_elections_service
node_logs_controller -->|"fetches paginated logs"| node_logs_service
node_main -->|"creates application"| node_app_module
node_main -->|"registers globally"| node_exceptions
node_main -->|"registers globally"| node_logging
node_users_controller -->|"protects routes"| node_jwt_guard
node_announcements_controller -->|"protects routes"| node_jwt_guard
node_resources_controller -->|"protects routes"| node_jwt_guard
node_elections_controller -->|"protects routes"| node_jwt_guard
node_logs_controller -->|"protects routes"| node_jwt_guard
node_jwt_guard -->|"validates token"| node_jwt_strategy
node_users_controller -->|"checks privileged roles"| node_roles_guard
node_announcements_controller -->|"checks privileged roles"| node_roles_guard
node_resources_controller -->|"checks privileged roles"| node_roles_guard
node_elections_controller -->|"checks privileged roles"| node_roles_guard
node_logs_controller -->|"checks privileged roles"| node_roles_guard

click node_auth_controller "https://github.com/thamesblanq/ulads-back/blob/main/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/thamesblanq/ulads-back/blob/main/src/auth/auth.service.ts"
click node_users_controller "https://github.com/thamesblanq/ulads-back/blob/main/src/users/users.controller.ts"
click node_users_service "https://github.com/thamesblanq/ulads-back/blob/main/src/users/users.service.ts"
click node_jwt_guard "https://github.com/thamesblanq/ulads-back/blob/main/src/auth/jwt-auth.guard.ts"
click node_jwt_strategy "https://github.com/thamesblanq/ulads-back/blob/main/src/auth/jwt.strategy.ts"
click node_roles_guard "https://github.com/thamesblanq/ulads-back/blob/main/src/auth/guards/roles.guard.ts"
click node_announcements_controller "https://github.com/thamesblanq/ulads-back/blob/main/src/announcements/announcements.controller.ts"
click node_announcements_service "https://github.com/thamesblanq/ulads-back/blob/main/src/announcements/announcements.service.ts"
click node_resources_controller "https://github.com/thamesblanq/ulads-back/blob/main/src/resources/resources.controller.ts"
click node_resources_service "https://github.com/thamesblanq/ulads-back/blob/main/src/resources/resources.service.ts"
click node_chat_gateway "https://github.com/thamesblanq/ulads-back/blob/main/src/chat/chat.gateway.ts"
click node_elections_controller "https://github.com/thamesblanq/ulads-back/blob/main/src/elections/elections.controller.ts"
click node_elections_service "https://github.com/thamesblanq/ulads-back/blob/main/src/elections/elections.service.ts"
click node_logs_controller "https://github.com/thamesblanq/ulads-back/blob/main/src/logs/logs.controller.ts"
click node_logs_service "https://github.com/thamesblanq/ulads-back/blob/main/src/logs/logs.service.ts"
click node_postgres "https://github.com/thamesblanq/ulads-back/blob/main/src/config/database.ts"
click node_main "https://github.com/thamesblanq/ulads-back/blob/main/src/main.ts"
click node_exceptions "https://github.com/thamesblanq/ulads-back/blob/main/src/common/filters/all-exceptions.filter.ts"
click node_logging "https://github.com/thamesblanq/ulads-back/blob/main/src/common/intercerptors/logging.intercerptor.ts"
click node_app_module "https://github.com/thamesblanq/ulads-back/blob/main/src/app.module.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_auth_controller,node_auth_service,node_users_controller,node_users_service,node_jwt_guard,node_jwt_strategy,node_roles_guard,node_client toneBlue
class node_announcements_controller,node_announcements_service,node_resources_controller,node_resources_service,node_chat_gateway toneAmber
class node_elections_controller,node_elections_service,node_logs_controller,node_logs_service toneMint
class node_postgres,node_main,node_exceptions,node_logging,node_app_module toneRose
class node_mail toneIndigo
```

## Components

### Identity & Access

- [Auth routes](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/auth.controller.ts): `src/auth/auth.controller.ts`
- [Auth service](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [User routes](https://github.com/thamesblanq/ulads-back/blob/main/src/users/users.controller.ts): `src/users/users.controller.ts`
- [Users service](https://github.com/thamesblanq/ulads-back/blob/main/src/users/users.service.ts): `src/users/users.service.ts`
- [JWT guard](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/jwt-auth.guard.ts): `src/auth/jwt-auth.guard.ts`
- [JWT strategy](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/jwt.strategy.ts): `src/auth/jwt.strategy.ts`
- [Roles guard](https://github.com/thamesblanq/ulads-back/blob/main/src/auth/guards/roles.guard.ts): `src/auth/guards/roles.guard.ts`

### Member Features

- [Announcement routes](https://github.com/thamesblanq/ulads-back/blob/main/src/announcements/announcements.controller.ts): `src/announcements/announcements.controller.ts`
- [Announcements service](https://github.com/thamesblanq/ulads-back/blob/main/src/announcements/announcements.service.ts): `src/announcements/announcements.service.ts`
- [Resource routes](https://github.com/thamesblanq/ulads-back/blob/main/src/resources/resources.controller.ts): `src/resources/resources.controller.ts`
- [Resources service](https://github.com/thamesblanq/ulads-back/blob/main/src/resources/resources.service.ts): `src/resources/resources.service.ts`
- [Realtime chat](https://github.com/thamesblanq/ulads-back/blob/main/src/chat/chat.gateway.ts): `src/chat/chat.gateway.ts`

### Elections & Oversight

- [Election routes](https://github.com/thamesblanq/ulads-back/blob/main/src/elections/elections.controller.ts): `src/elections/elections.controller.ts`
- [Elections service](https://github.com/thamesblanq/ulads-back/blob/main/src/elections/elections.service.ts): `src/elections/elections.service.ts`
- [Audit log routes](https://github.com/thamesblanq/ulads-back/blob/main/src/logs/logs.controller.ts): `src/logs/logs.controller.ts`
- [Logs service](https://github.com/thamesblanq/ulads-back/blob/main/src/logs/logs.service.ts): `src/logs/logs.service.ts`

### API Runtime

- [PostgreSQL](https://github.com/thamesblanq/ulads-back/blob/main/src/config/database.ts): `src/config/database.ts`
- [Nest bootstrap](https://github.com/thamesblanq/ulads-back/blob/main/src/main.ts): `src/main.ts`
- [Error filter](https://github.com/thamesblanq/ulads-back/blob/main/src/common/filters/all-exceptions.filter.ts): `src/common/filters/all-exceptions.filter.ts`
- [Request logging](https://github.com/thamesblanq/ulads-back/blob/main/src/common/intercerptors/logging.intercerptor.ts): `src/common/intercerptors/logging.intercerptor.ts`
- [Application modules](https://github.com/thamesblanq/ulads-back/blob/main/src/app.module.ts): `src/app.module.ts`

### Other components

- **Platform client**
- **SMTP email**

## Connections

- Platform client → Auth routes: sends auth requests
- Platform client → User routes: manages accounts
- Platform client → Announcement routes: uses announcements
- Platform client → Resource routes: browses resources
- Platform client → Election routes: votes and views
- Platform client → Audit log routes: requests audit logs
- Platform client → Realtime chat: opens chat
- Auth routes → Auth service: delegates auth
- Auth service → Users service: looks up users
- Auth service → PostgreSQL: reads and updates
- Auth service → SMTP email: sends reset email
- User routes → Users service: delegates account actions
- Announcement routes → Announcements service: delegates announcements
- Resource routes → Resources service: delegates resources
- Election routes → Elections service: delegates election actions
- Audit log routes → Logs service: fetches paginated logs
- Nest bootstrap → Application modules: creates application
- Nest bootstrap → Error filter: registers globally
- Nest bootstrap → Request logging: registers globally
- User routes → JWT guard: protects routes
- Announcement routes → JWT guard: protects routes
- Resource routes → JWT guard: protects routes
- Election routes → JWT guard: protects routes
- Audit log routes → JWT guard: protects routes
- JWT guard → JWT strategy: validates token
- User routes → Roles guard: checks privileged roles
- Announcement routes → Roles guard: checks privileged roles
- Resource routes → Roles guard: checks privileged roles
- Election routes → Roles guard: checks privileged roles
- Audit log routes → Roles guard: checks privileged roles