How cocsi-mg/hubcefet works
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: app.module.ts Doc Flow API · doc-flow-client Doc Flow Client · config.js PostgreSQL · docker-compose.yml Compose
Components 22
Edge & Ops
Request routing, containers, and operational services
Frontend SPA
React client and UI composition
- Doc Flow Client · Frontend application shell
apps/doc-flow-client - Routing · App routes and layout composition
apps/doc-flow-client/src/router/index.tsx - Auth UI · Login, signup, magic login, and route guards
apps/doc-flow-client/src/pages/auth/Login.tsx - Domain Views · Events, files, certificates, profiles, and user management screens
apps/doc-flow-client/src/pages/certificates/CertificateDashboard.tsx - Shared UI · Reusable primitives and feature components
apps/doc-flow-client/src/components/ui/button.tsx - API Client · Shared Axios instance and typed service wrappers
apps/doc-flow-client/src/api/axios-instance.ts - Schemas & Types · Local payload schemas and frontend type models
apps/doc-flow-client/src/lib/schemas/auth/index.schema.ts - Auth State · 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 · Backend application shell and module graph
apps/doc-flow/src/app.module.ts - Identity · Sign-in, sign-up, magic links, guards, roles, and profile access
apps/doc-flow/src/auth/auth.module.ts - Core Domains · Users, profiles, events, presences, and role-backed domain APIs
apps/doc-flow/src/events/events.module.ts - Files · File upload, metadata, status, and download handling
apps/doc-flow/src/files/files.module.ts - Activities · Activity review, reviewers, histories, and certificate handling
apps/doc-flow/src/activities/activities.module.ts - Async Jobs · PDF generation and mail processing off the request path
apps/doc-flow/src/queues/queues.module.ts - Shared HTTP · Common response and error infrastructure, Swagger loading
apps/doc-flow/src/lib/interceptors/response.interceptor.ts
Data & Async
Persistent storage and background processing
- PostgreSQL · Primary system of record
apps/doc-flow/database/config/config.js - Redis · Backing store for asynchronous jobs
- Storage · Local persisted files and generated outputs
apps/doc-flow/storage
Connections 30
- 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