# instituto-educar-aparecida/backend architecture

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

- Interactive diagram: https://gitdiagram.com/instituto-educar-aparecida/backend
- Repository: https://github.com/instituto-educar-aparecida/backend

## Overview

1. **Project shape**
   - This repository is the **backend for Instituto Educar - Aparecida**.
   - It is a **Node.js application backed by PostgreSQL**, packaged to run in Docker.
   - The README also references a separate frontend and pgAdmin, but the tree here is primarily the API + persistence layer.

2. **Runtime and deployment boundary**
   - `Dockerfile` and `docker-compose.yml` define the local runtime stack.
   - The composed environment has three main containers: **app**, **Postgres**, and **pgAdmin**.
   - `.env.example` indicates configuration is externalized, so app behavior is environment-driven rather than hardcoded.

3. **Application entry and API surface**
   - `index.js` is the main server entrypoint.
   - `index.html` exists at the root, but the architectural center of this repo is the backend API rather than a browser app.
   - `swagger.js` suggests the API is documented/exposed through Swagger/OpenAPI.

4. **HTTP routing layer**
   - `src/routes/` is the HTTP boundary and splits the API into functional areas:
     - `authRoutes.js`
     - `adminRoutes.js`
     - `studentRoutes.js`
     - `professorRoutes.js`
     - `aulasRoutes.js`
     - `videoRoutes.js`
   - This indicates the system is organized by **role** and **education workflow** rather than by generic CRUD modules.

5. **Authorization and request gating**
   - `src/routes/MiddlewereRoutes.js` is the central middleware layer.
   - It likely handles authentication, authorization, and/or role-based access control before requests reach controllers.
   - This is an important architectural boundary between public/authenticated routes and privileged areas like admin/professor/student functions.

6. **Controller layer**
   - `src/routes/Controllers/` contains request handlers:
     - `authControllers.js`
     - `professorController.js`
   - Controllers appear to coordinate request parsing, validation, and calls into persistence/domain logic.
   - The layout suggests the API is intentionally thin at the route level and concentrates behavior in controllers.

7. **Domain model**
   - `src/domain/` holds the core business entities:
     - `User`
     - `Curso`
     - `Materia`
     - `Atividade`
     - `Progresso`
   - `schemas.js` likely centralizes data validation and/or entity schemas.
   - The domain model implies the product’s core concepts are **users, courses, subjects, activities, and progress tracking**.

8. **Persistence layer**
   - `src/database/` contains one data-access module per entity:
     - `UserDataAcess.js`
     - `CursoDataAcess.js`
     - `MateriaDataAcess.js`
     - `AtividadeDataAcess.js`
     - `LessonProgressDataAccess.js`
     - `ProgressoCurso.js`
   - This is a classic **manual data access layer**: the API code likely talks to PostgreSQL through these classes/modules rather than through a heavy ORM abstraction.
   - The presence of separate modules for course progress and lesson progress suggests progress is modeled as a first-class concern.

9. **Database initialization and schema management**
   - `src/database/init/` contains SQL scripts to create tables:
     - `CreateTable_User.sql`
     - `CreateTable_Curso.sql`
     - `CreateTable_Materia.sql`
     - `CreateTable_Atividade.sql`
     - `CreateTable_LessonProgress.sql`
     - `CreateTable-ProgressoCurso.sql`
   - These scripts are executed on a fresh database volume, so schema bootstrapping is **container-startup driven**.
   - `db_schema.md` provides the documented schema reference.

10. **Request-to-data flow**
   - Typical flow is:
     - client request hits a route,
     - middleware checks access,
     - controller processes the request,
     - domain/schema logic validates or shapes the data,
     - data-access module reads/writes PostgreSQL,
     - response returns to the client.
   - This keeps HTTP concerns, business concepts, and persistence separated.

11. **Cross-cutting concerns**
   - `src/logger.js` provides centralized logging, which likely supports observability and debugging across controllers/routes/data access.
   - The GitHub workflow `sonarcloud.yml` indicates code quality/static analysis is part of the repository’s engineering process.

12. **Operational tooling**
   - pgAdmin is used to inspect and manage the PostgreSQL database during development.
   - The README’s emphasis on volume initialization means database state is treated as disposable in dev, with schema recreated from SQL scripts when needed.

13. **Diagram summary**
   - The most accurate architecture diagram should show:
     - **Docker Compose** as the deployment wrapper,
     - **Node.js API** as the application core,
     - **Routes/Middleware/Controllers** as the HTTP layer,
     - **Domain models** as the business layer,
     - **Data-access modules** as the persistence layer,
     - **PostgreSQL** as the system of record,
     - **Swagger/pgAdmin** as supporting documentation/operations tools.

Main entry points: [`index.js`](https://github.com/instituto-educar-aparecida/backend/blob/main/index.js) (Server), [`src/domain/schemas.js`](https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/schemas.js) (Schemas), [`src/routes/Controllers/professorController.js`](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/Controllers/professorController.js) (Professor ctrl), [`src/routes/MiddlewereRoutes.js`](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/MiddlewereRoutes.js) (Access gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_docker_compose["Compose<br/>docker stack<br/>[docker-compose.yml]"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_env_example["Env sample<br/>config<br/>[.env.example]"]
  node_postgres[("PostgreSQL<br/>database")]
  node_pgadmin["pgAdmin<br/>admin tool"]
end

subgraph group_api["API"]
  node_entrypoint["Server<br/>node entry<br/>[index.js]"]
  node_swagger["Swagger<br/>api docs<br/>[swagger.js]"]
  node_middleware["Access gate<br/>auth middleware"]
  node_auth_routes["Auth routes<br/>http routes<br/>[authRoutes.js]"]
  node_admin_routes["Admin routes<br/>http routes<br/>[adminRoutes.js]"]
  node_student_routes["Student routes<br/>http routes<br/>[studentRoutes.js]"]
  node_professor_routes["Professor routes<br/>http routes<br/>[professorRoutes.js]"]
  node_aulas_routes["Aulas routes<br/>http routes<br/>[aulasRoutes.js]"]
  node_video_routes["Video routes<br/>http routes<br/>[videoRoutes.js]"]
  node_auth_controller["Auth ctrl<br/>controller<br/>[authControllers.js]"]
  node_prof_controller["Professor ctrl<br/>controller"]
end

subgraph group_domain["Domain"]
  node_user["User<br/>domain entity<br/>[User.js]"]
  node_curso["Curso<br/>domain entity<br/>[Curso.js]"]
  node_materia["Materia<br/>domain entity<br/>[Materia.js]"]
  node_atividade["Atividade<br/>domain entity<br/>[Atividade.js]"]
  node_progresso["Progresso<br/>domain entity<br/>[Progresso.js]"]
  node_schemas["Schemas<br/>validation schema<br/>[schemas.js]"]
end

subgraph group_data["Data"]
  node_user_dao["User DAO<br/>data access<br/>[UserDataAcess.js]"]
  node_curso_dao["Curso DAO<br/>data access<br/>[CursoDataAcess.js]"]
  node_materia_dao["Materia DAO<br/>data access"]
  node_atividade_dao["Atividade DAO<br/>data access"]
  node_lesson_progress_dao["Lesson progress<br/>data access"]
  node_curso_progress_dao["Curso progress<br/>data access<br/>[ProgressoCurso.js]"]
  node_db_init["DB init SQL<br/>schema bootstrap"]
end

node_docker_compose -->|"runs"| node_entrypoint
node_docker_compose -->|"provisions"| node_postgres
node_docker_compose -->|"provisions"| node_pgadmin
node_dockerfile -->|"builds"| node_entrypoint
node_env_example -->|"configures"| node_entrypoint
node_entrypoint -->|"exposes"| node_swagger
node_entrypoint -->|"mounts"| node_auth_routes
node_entrypoint -->|"mounts"| node_admin_routes
node_entrypoint -->|"mounts"| node_student_routes
node_entrypoint -->|"mounts"| node_professor_routes
node_entrypoint -->|"mounts"| node_aulas_routes
node_entrypoint -->|"mounts"| node_video_routes
node_auth_routes -->|"guards"| node_middleware
node_admin_routes -->|"guards"| node_middleware
node_student_routes -->|"guards"| node_middleware
node_professor_routes -->|"guards"| node_middleware
node_auth_routes -->|"delegates"| node_auth_controller
node_professor_routes -->|"delegates"| node_prof_controller
node_auth_controller -->|"validates"| node_schemas
node_prof_controller -->|"validates"| node_schemas
node_auth_controller -->|"reads/writes"| node_user_dao
node_prof_controller -->|"reads/writes"| node_curso_dao
node_prof_controller -->|"reads/writes"| node_materia_dao
node_user -->|"shaped by"| node_schemas
node_curso -->|"shaped by"| node_schemas
node_materia -->|"shaped by"| node_schemas
node_atividade -->|"shaped by"| node_schemas
node_progresso -->|"shaped by"| node_schemas
node_user_dao -->|"persists"| node_postgres
node_curso_dao -->|"persists"| node_postgres
node_materia_dao -->|"persists"| node_postgres
node_atividade_dao -->|"persists"| node_postgres
node_lesson_progress_dao -->|"persists"| node_postgres
node_curso_progress_dao -->|"persists"| node_postgres
node_db_init -->|"boots schema"| node_postgres
node_postgres -.->|"inspected by"| node_pgadmin

click node_docker_compose "https://github.com/instituto-educar-aparecida/backend/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/instituto-educar-aparecida/backend/tree/main/Dockerfile"
click node_env_example "https://github.com/instituto-educar-aparecida/backend/blob/main/.env.example"
click node_entrypoint "https://github.com/instituto-educar-aparecida/backend/blob/main/index.js"
click node_swagger "https://github.com/instituto-educar-aparecida/backend/blob/main/swagger.js"
click node_middleware "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/MiddlewereRoutes.js"
click node_auth_routes "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/authRoutes.js"
click node_admin_routes "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/adminRoutes.js"
click node_student_routes "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/studentRoutes.js"
click node_professor_routes "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/professorRoutes.js"
click node_aulas_routes "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/aulasRoutes.js"
click node_video_routes "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/videoRoutes.js"
click node_auth_controller "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/Controllers/authControllers.js"
click node_prof_controller "https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/Controllers/professorController.js"
click node_user "https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/User.js"
click node_curso "https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Curso.js"
click node_materia "https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Materia.js"
click node_atividade "https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Atividade.js"
click node_progresso "https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Progresso.js"
click node_schemas "https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/schemas.js"
click node_user_dao "https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/UserDataAcess.js"
click node_curso_dao "https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/CursoDataAcess.js"
click node_materia_dao "https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/MateriaDataAcess.js"
click node_atividade_dao "https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/AtividadeDataAcess.js"
click node_lesson_progress_dao "https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/LessonProgressDataAccess.js"
click node_curso_progress_dao "https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/ProgressoCurso.js"
click node_db_init "https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/init/CreateTable_User.sql"

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_docker_compose,node_dockerfile,node_env_example,node_postgres,node_pgadmin toneBlue
class node_entrypoint,node_swagger,node_middleware,node_auth_routes,node_admin_routes,node_student_routes,node_professor_routes,node_aulas_routes,node_video_routes,node_auth_controller,node_prof_controller toneAmber
class node_user,node_curso,node_materia,node_atividade,node_progresso,node_schemas toneMint
class node_user_dao,node_curso_dao,node_materia_dao,node_atividade_dao,node_lesson_progress_dao,node_curso_progress_dao,node_db_init toneRose
```

## Components

### Deployment

Container and environment boundary

- [Compose](https://github.com/instituto-educar-aparecida/backend/blob/main/docker-compose.yml): docker stack · Defines app, database, and admin services · `docker-compose.yml`
- [Dockerfile](https://github.com/instituto-educar-aparecida/backend/tree/main/Dockerfile): container build · Builds the Node.js application image · `Dockerfile`
- [Env sample](https://github.com/instituto-educar-aparecida/backend/blob/main/.env.example): config · Externalized runtime configuration template · `.env.example`
- **PostgreSQL**: database · System of record for application data
- **pgAdmin**: admin tool · Database inspection and management UI

### API

HTTP entrypoints and request handling

- [Server](https://github.com/instituto-educar-aparecida/backend/blob/main/index.js): node entry · Main application startup entrypoint · `index.js`
- [Swagger](https://github.com/instituto-educar-aparecida/backend/blob/main/swagger.js): api docs · OpenAPI/Swagger surface for the backend · `swagger.js`
- [Access gate](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/MiddlewereRoutes.js): auth middleware · Central request gating and role checks · `src/routes/MiddlewereRoutes.js`
- [Auth routes](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/authRoutes.js): http routes · Authentication endpoints · `src/routes/authRoutes.js`
- [Admin routes](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/adminRoutes.js): http routes · Administrative endpoints · `src/routes/adminRoutes.js`
- [Student routes](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/studentRoutes.js): http routes · Student-facing endpoints · `src/routes/studentRoutes.js`
- [Professor routes](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/professorRoutes.js): http routes · Professor-facing endpoints · `src/routes/professorRoutes.js`
- [Aulas routes](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/aulasRoutes.js): http routes · Lesson and class endpoints · `src/routes/aulasRoutes.js`
- [Video routes](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/videoRoutes.js): http routes · Video-related endpoints · `src/routes/videoRoutes.js`
- [Auth ctrl](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/Controllers/authControllers.js): controller · Handles auth request orchestration · `src/routes/Controllers/authControllers.js`
- [Professor ctrl](https://github.com/instituto-educar-aparecida/backend/blob/main/src/routes/Controllers/professorController.js): controller · Handles professor workflows · `src/routes/Controllers/professorController.js`

### Domain

Core business concepts

- [User](https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/User.js): domain entity · Account and identity model · `src/domain/User.js`
- [Curso](https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Curso.js): domain entity · Course model · `src/domain/Curso.js`
- [Materia](https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Materia.js): domain entity · Subject model · `src/domain/Materia.js`
- [Atividade](https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Atividade.js): domain entity · Activity model · `src/domain/Atividade.js`
- [Progresso](https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/Progresso.js): domain entity · Progress tracking model · `src/domain/Progresso.js`
- [Schemas](https://github.com/instituto-educar-aparecida/backend/blob/main/src/domain/schemas.js): validation schema · Shared domain validation and shaping rules · `src/domain/schemas.js`

### Data

Persistence and schema bootstrapping

- [User DAO](https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/UserDataAcess.js): data access · User persistence module · `src/database/UserDataAcess.js`
- [Curso DAO](https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/CursoDataAcess.js): data access · Course persistence module · `src/database/CursoDataAcess.js`
- [Materia DAO](https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/MateriaDataAcess.js): data access · Subject persistence module · `src/database/MateriaDataAcess.js`
- [Atividade DAO](https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/AtividadeDataAcess.js): data access · Activity persistence module · `src/database/AtividadeDataAcess.js`
- [Lesson progress](https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/LessonProgressDataAccess.js): data access · Per-lesson progress persistence · `src/database/LessonProgressDataAccess.js`
- [Curso progress](https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/ProgressoCurso.js): data access · Course progress persistence · `src/database/ProgressoCurso.js`
- [DB init SQL](https://github.com/instituto-educar-aparecida/backend/blob/main/src/database/init/CreateTable_User.sql): schema bootstrap · Startup SQL scripts that create tables · `src/database/init/CreateTable_User.sql`

## Connections

- Compose → Server: runs · Compose starts the application container
- Compose → PostgreSQL: provisions · Compose includes PostgreSQL as a service
- Compose → pgAdmin: provisions · Compose includes pgAdmin as a service
- Dockerfile → Server: builds · Container image packages the Node.js server
- Env sample → Server: configures · Environment variables drive runtime behavior
- Server → Swagger: exposes · Server publishes documented API surface
- Server → Auth routes: mounts · Main server registers route modules
- Server → Admin routes: mounts · Main server registers route modules
- Server → Student routes: mounts · Main server registers route modules
- Server → Professor routes: mounts · Main server registers route modules
- Server → Aulas routes: mounts · Main server registers route modules
- Server → Video routes: mounts · Main server registers route modules
- Auth routes → Access gate: guards · Authentication routes pass through shared access checks
- Admin routes → Access gate: guards · Administrative routes pass through shared access checks
- Student routes → Access gate: guards · Student routes pass through shared access checks
- Professor routes → Access gate: guards · Professor routes pass through shared access checks
- Auth routes → Auth ctrl: delegates · Auth routes forward to controller logic
- Professor routes → Professor ctrl: delegates · Professor routes forward to controller logic
- Auth ctrl → Schemas: validates · Controllers rely on shared schema rules
- Professor ctrl → Schemas: validates · Controllers rely on shared schema rules
- Auth ctrl → User DAO: reads/writes · Authentication touches user persistence
- Professor ctrl → Curso DAO: reads/writes · Professor workflows touch course data
- Professor ctrl → Materia DAO: reads/writes · Professor workflows touch subject data
- User → Schemas: shaped by · Domain entities are constrained by shared schemas
- Curso → Schemas: shaped by · Domain entities are constrained by shared schemas
- Materia → Schemas: shaped by · Domain entities are constrained by shared schemas
- Atividade → Schemas: shaped by · Domain entities are constrained by shared schemas
- Progresso → Schemas: shaped by · Domain entities are constrained by shared schemas
- User DAO → PostgreSQL: persists · User records are stored in PostgreSQL
- Curso DAO → PostgreSQL: persists · Course records are stored in PostgreSQL
- Materia DAO → PostgreSQL: persists · Subject records are stored in PostgreSQL
- Atividade DAO → PostgreSQL: persists · Activity records are stored in PostgreSQL
- Lesson progress → PostgreSQL: persists · Lesson progress is stored in PostgreSQL
- Curso progress → PostgreSQL: persists · Course progress is stored in PostgreSQL
- DB init SQL → PostgreSQL: boots schema · SQL scripts initialize tables on fresh volumes
- PostgreSQL → pgAdmin: inspected by · pgAdmin is used to inspect and manage the database
