# cocsi-mg/hubcefet architecture

> Architecture diagram of the GitHub repository cocsi-mg/hubcefet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cocsi-mg/hubcefet
- Repository: https://github.com/cocsi-mg/hubcefet

## Overview

1. **Overall shape**
   - This is a two-app monorepo: `apps/doc-flow-client` is the React SPA frontend, and `apps/doc-flow` is the NestJS API backend.
   - The production edge is an `nginx` reverse proxy that serves the SPA and forwards `/api/*` to the backend.

2. **Request path and deployment boundary**
   - Browser traffic lands on `nginx`.
   - `nginx` routes UI requests to the frontend container and API requests to the NestJS container.
   - Static assets are served from the frontend build; backend traffic stays behind the proxy.
   - `Adminer` is a separate operational service for inspecting PostgreSQL.

3. **Frontend subsystem**
   - The client is a Vite + React + TypeScript application.
   - Routing is organized around layouts and pages for auth, app selection, profile, events, files, user management, complementary/extension activity types, and certificate workflows.
   - UI components are split into reusable primitives, domain-specific components, and page-level views.

4. **Frontend-to-API integration**
   - The frontend talks to the backend through a shared Axios instance and typed service wrappers under `src/api/services`.
   - Data contracts are validated/modeled with local schemas and type definitions, so the UI has a typed boundary around API payloads.
   - Auth state is held in a context provider and accessed through hooks, with route protection handled by private/profile route components.

5. **Backend module structure**
   - The backend is modular NestJS: `auth`, `users`, `roles`, `profile`, `events`, `presences`, `files`, `activities`, `complementary-activity-type`, `extension-activity-type`, `email`, and `queues`.
   - Each domain module typically contains controller, service, DTOs, entities, and repository abstractions.
   - This suggests a layered architecture: HTTP controllers at the edge, services for business logic, repositories for persistence.

6. **Identity and access control**
   - Authentication covers sign-in, sign-up, magic-link login, and access-token issuance.
   - Authorization is enforced with guards and decorators for public access, roles, and profile-based access.
   - The frontend mirrors this with auth layouts, private routes, and user/profile management screens.

7. **Core domain flows**
   - `events` and `presences` model event creation, editing, attendance capture, and location-aware attendance checks.
   - The frontend includes scanner, map, manual presence, and subscription UI, which aligns with the backend’s event/presence workflow.
   - `files` handles uploads, status tracking, downloads, and file metadata, likely supporting document submission/review flows.
   - `activities` appears to be the main document/certificate review domain, with reviewer history, review settings, and certificate file handling.

8. **Background processing and async work**
   - Redis is used as a queue backend for asynchronous jobs.
   - The `queues` module contains PDF generation, and the `email` module has a queue processor for sending mail.
   - This keeps heavyweight work such as document rendering and email delivery off the request path.

9. **Persistence boundary**
   - PostgreSQL is the primary system of record.
   - Database structure is managed through Sequelize migrations and seeders in `apps/doc-flow/database`.
   - The migration history shows evolution across users/roles/profiles, classes/events/presences/files, and the newer activity-review domains.

10. **Operational concerns**
   - The repo is container-first: there are Dockerfiles for both apps, a top-level `docker-compose.yml`, and setup scripts for Linux/Windows.
   - The backend exposes Swagger loading utilities and shared response/error infrastructure, including a response interceptor and global filter.
   - Frontend and backend both read from the root `.env`, which is important for diagramming config flow.

11. **Storage and generated artifacts**
   - The backend also has a local `storage/` area, implying file artifacts are persisted outside the database.
   - Generated outputs such as PDFs or uploaded documents likely move between request handlers, queues, and storage before being exposed back to the client.

12. **What to show in an architecture diagram**
   - Draw `Browser -> nginx -> {frontend SPA, NestJS API}` as the main flow.
   - Under the API, show modules for auth/identity, events-presences, files, activities, and notification/queue processing.
   - Add PostgreSQL as the durable data store, Redis as the async job backbone, and Adminer as an operator-facing side tool.

Main entry points: [`apps/doc-flow/src/app.module.ts`](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/app.module.ts) (Doc Flow API), [`apps/doc-flow-client`](https://github.com/cocsi-mg/hubcefet/tree/main/apps/doc-flow-client) (Doc Flow Client), [`apps/doc-flow/database/config/config.js`](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/database/config/config.js) (PostgreSQL), [`docker-compose.yml`](https://github.com/cocsi-mg/hubcefet/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Edge & Ops"]
  node_browser(("Browser<br/>client"))
  node_nginx["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_adminer["Adminer<br/>db admin"]
end

subgraph group_frontend["Frontend SPA"]
  node_client["Doc Flow Client<br/>Vite React SPA"]
  node_router["Routing<br/>route/layout layer<br/>[index.tsx]"]
  node_authui["Auth UI<br/>auth screens<br/>[Login.tsx]"]
  node_domainui["Domain Views<br/>feature pages"]
  node_ui["Shared UI<br/>components<br/>[button.tsx]"]
  node_api["API Client<br/>axios services<br/>[axios-instance.ts]"]
  node_schemas["Schemas & Types<br/>contracts<br/>[index.schema.ts]"]
  node_authstate["Auth State<br/>context/hooks<br/>[AuthProvider.tsx]"]
end

subgraph group_backend["NestJS API"]
  node_backendapp["Doc Flow API<br/>NestJS app<br/>[app.module.ts]"]
  node_authmod["Identity<br/>auth/access control<br/>[auth.module.ts]"]
  node_domainmods["Core Domains<br/>business modules<br/>[events.module.ts]"]
  node_filesmod["Files<br/>upload service<br/>[files.module.ts]"]
  node_activitiesmod["Activities<br/>review workflow"]
  node_queuesmod["Async Jobs<br/>queue workers<br/>[queues.module.ts]"]
  node_sharedlib["Shared HTTP<br/>filters/interceptors"]
end

subgraph group_data["Data & Async"]
  node_postgres[("PostgreSQL<br/>database<br/>[config.js]")]
  node_redis[("Redis<br/>queue backend")]
  node_storage[("Storage<br/>file artifacts")]
end

node_browser -->|"HTTP traffic"| node_nginx
node_nginx -->|"serve SPA"| node_client
node_nginx -->|"proxy /api"| node_backendapp
node_compose -->|"starts"| node_nginx
node_compose -->|"starts"| node_adminer
node_compose -->|"provisions"| node_postgres
node_compose -->|"provisions"| node_redis
node_client -->|"uses"| node_router
node_client -->|"renders"| node_authui
node_client -->|"renders"| node_domainui
node_client -->|"composes"| node_ui
node_client -->|"calls"| node_api
node_client -->|"validates"| node_schemas
node_client -->|"guards"| node_authstate
node_api -.->|"matches"| node_backendapp
node_backendapp -->|"loads"| node_authmod
node_backendapp -->|"loads"| node_domainmods
node_backendapp -->|"loads"| node_filesmod
node_backendapp -->|"loads"| node_activitiesmod
node_backendapp -->|"loads"| node_queuesmod
node_backendapp -->|"uses"| node_sharedlib
node_authmod -->|"stores users"| node_postgres
node_domainmods -->|"stores domain data"| node_postgres
node_filesmod -->|"stores metadata"| node_postgres
node_filesmod -->|"writes files"| node_storage
node_activitiesmod -->|"stores reviews"| node_postgres
node_activitiesmod -->|"enqueues PDF"| node_queuesmod
node_queuesmod -->|"consumes jobs"| node_redis
node_queuesmod -->|"produces artifacts"| node_storage
node_backendapp -->|"reads/writes"| node_postgres

click node_nginx "https://github.com/cocsi-mg/hubcefet/blob/main/nginx.conf"
click node_compose "https://github.com/cocsi-mg/hubcefet/blob/main/docker-compose.yml"
click node_client "https://github.com/cocsi-mg/hubcefet/tree/main/apps/doc-flow-client"
click node_router "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/router/index.tsx"
click node_authui "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/pages/auth/Login.tsx"
click node_domainui "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/pages/certificates/CertificateDashboard.tsx"
click node_ui "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/components/ui/button.tsx"
click node_api "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/api/axios-instance.ts"
click node_schemas "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/lib/schemas/auth/index.schema.ts"
click node_authstate "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/context/AuthProvider.tsx"
click node_backendapp "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/app.module.ts"
click node_authmod "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/auth/auth.module.ts"
click node_domainmods "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/events/events.module.ts"
click node_filesmod "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/files/files.module.ts"
click node_activitiesmod "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/activities/activities.module.ts"
click node_queuesmod "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/queues/queues.module.ts"
click node_sharedlib "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/lib/interceptors/response.interceptor.ts"
click node_postgres "https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/database/config/config.js"
click node_storage "https://github.com/cocsi-mg/hubcefet/tree/main/apps/doc-flow/storage"

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_browser,node_nginx,node_compose,node_adminer toneBlue
class node_client,node_router,node_authui,node_domainui,node_ui,node_api,node_schemas,node_authstate toneAmber
class node_backendapp,node_authmod,node_domainmods,node_filesmod,node_activitiesmod,node_queuesmod,node_sharedlib toneMint
class node_postgres,node_redis,node_storage toneRose
```

## Components

### Edge & Ops

Request routing, containers, and operational services

- **Browser**: client · User traffic entry point
- [Nginx](https://github.com/cocsi-mg/hubcefet/blob/main/nginx.conf): reverse proxy · Serves SPA and forwards API requests · `nginx.conf`
- [Compose](https://github.com/cocsi-mg/hubcefet/blob/main/docker-compose.yml): deployment · Container orchestration for the stack · `docker-compose.yml`
- **Adminer**: db admin · Operator UI for PostgreSQL inspection

### Frontend SPA

React client and UI composition

- [Doc Flow Client](https://github.com/cocsi-mg/hubcefet/tree/main/apps/doc-flow-client): Vite React SPA · Frontend application shell · `apps/doc-flow-client`
- [Routing](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/router/index.tsx): route/layout layer · App routes and layout composition · `apps/doc-flow-client/src/router/index.tsx`
- [Auth UI](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/pages/auth/Login.tsx): auth screens · Login, signup, magic login, and route guards · `apps/doc-flow-client/src/pages/auth/Login.tsx`
- [Domain Views](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/pages/certificates/CertificateDashboard.tsx): feature pages · Events, files, certificates, profiles, and user management screens · `apps/doc-flow-client/src/pages/certificates/CertificateDashboard.tsx`
- [Shared UI](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/components/ui/button.tsx): components · Reusable primitives and feature components · `apps/doc-flow-client/src/components/ui/button.tsx`
- [API Client](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/api/axios-instance.ts): axios services · Shared Axios instance and typed service wrappers · `apps/doc-flow-client/src/api/axios-instance.ts`
- [Schemas & Types](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/lib/schemas/auth/index.schema.ts): contracts · Local payload schemas and frontend type models · `apps/doc-flow-client/src/lib/schemas/auth/index.schema.ts`
- [Auth State](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow-client/src/context/AuthProvider.tsx): context/hooks · Auth provider, hooks, and protected route logic · `apps/doc-flow-client/src/context/AuthProvider.tsx`

### NestJS API

Modular backend and domain services

- [Doc Flow API](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/app.module.ts): NestJS app · Backend application shell and module graph · `apps/doc-flow/src/app.module.ts`
- [Identity](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/auth/auth.module.ts): auth/access control · Sign-in, sign-up, magic links, guards, roles, and profile access · `apps/doc-flow/src/auth/auth.module.ts`
- [Core Domains](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/events/events.module.ts): business modules · Users, profiles, events, presences, and role-backed domain APIs · `apps/doc-flow/src/events/events.module.ts`
- [Files](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/files/files.module.ts): upload service · File upload, metadata, status, and download handling · `apps/doc-flow/src/files/files.module.ts`
- [Activities](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/activities/activities.module.ts): review workflow · Activity review, reviewers, histories, and certificate handling · `apps/doc-flow/src/activities/activities.module.ts`
- [Async Jobs](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/queues/queues.module.ts): queue workers · PDF generation and mail processing off the request path · `apps/doc-flow/src/queues/queues.module.ts`
- [Shared HTTP](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/src/lib/interceptors/response.interceptor.ts): filters/interceptors · Common response and error infrastructure, Swagger loading · `apps/doc-flow/src/lib/interceptors/response.interceptor.ts`

### Data & Async

Persistent storage and background processing

- [PostgreSQL](https://github.com/cocsi-mg/hubcefet/blob/main/apps/doc-flow/database/config/config.js): database · Primary system of record · `apps/doc-flow/database/config/config.js`
- **Redis**: queue backend · Backing store for asynchronous jobs
- [Storage](https://github.com/cocsi-mg/hubcefet/tree/main/apps/doc-flow/storage): file artifacts · Local persisted files and generated outputs · `apps/doc-flow/storage`

## Connections

- Browser → Nginx: HTTP traffic · User requests enter the deployment edge
- Nginx → Doc Flow Client: serve SPA · Static frontend assets are served from the client build
- Nginx → Doc Flow API: proxy /api · API requests are forwarded to NestJS
- Compose → Nginx: starts · Compose wires the edge service into the stack
- Compose → Adminer: starts · Operational database viewer is deployed separately
- Compose → PostgreSQL: provisions · Primary database runs as part of the container stack
- Compose → Redis: provisions · Async job backend is part of the container stack
- Doc Flow Client → Routing: uses · Route and layout hierarchy drive the SPA
- Doc Flow Client → Auth UI: renders · Authentication screens and route protection
- Doc Flow Client → Domain Views: renders · Feature pages for core workflows
- Doc Flow Client → Shared UI: composes · Reusable components and primitives
- Doc Flow Client → API Client: calls · Frontend requests flow through typed service wrappers
- Doc Flow Client → Schemas & Types: validates · Payloads are modeled with local schemas and types
- Doc Flow Client → Auth State: guards · Auth context and hooks gate private/profile routes
- API Client → Doc Flow API: matches · Typed client boundary corresponds to backend modules
- Doc Flow API → Identity: loads · Authentication and authorization module
- Doc Flow API → Core Domains: loads · Core CRUD and workflow modules
- Doc Flow API → Files: loads · File handling module
- Doc Flow API → Activities: loads · Certificate and review workflow module
- Doc Flow API → Async Jobs: loads · Background processing module
- Doc Flow API → Shared HTTP: uses · Global response and error infrastructure
- Identity → PostgreSQL: stores users · Identity data persists in PostgreSQL
- Core Domains → PostgreSQL: stores domain data · Users, profiles, events, and presences persist in PostgreSQL
- Files → PostgreSQL: stores metadata · File state and metadata are persisted
- Files → Storage: writes files · Uploaded and generated file artifacts move to local storage
- Activities → PostgreSQL: stores reviews · Review history, settings, and activity records persist
- Activities → Async Jobs: enqueues PDF · Certificate rendering is delegated to background jobs
- Async Jobs → Redis: consumes jobs · Workers process queued PDF and email work
- Async Jobs → Storage: produces artifacts · Generated PDFs are written out for later download
- Doc Flow API → PostgreSQL: reads/writes · Main persistence boundary
