How instituto-educar-aparecida/backend works
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 Server · schemas.js Schemas · professorController.js Professor ctrl · MiddlewereRoutes.js Access gate
Components 29
Deployment
Container and environment boundary
- Compose · Defines app, database, and admin services
docker-compose.yml - Dockerfile · Builds the Node.js application image
Dockerfile - Env sample · Externalized runtime configuration template
.env.example - PostgreSQL · System of record for application data
- pgAdmin · Database inspection and management UI
API
HTTP entrypoints and request handling
- Server · Main application startup entrypoint
index.js - Swagger · OpenAPI/Swagger surface for the backend
swagger.js - Access gate · Central request gating and role checks
src/routes/MiddlewereRoutes.js - Auth routes · Authentication endpoints
src/routes/authRoutes.js - Admin routes · Administrative endpoints
src/routes/adminRoutes.js - Student routes · Student-facing endpoints
src/routes/studentRoutes.js - Professor routes · Professor-facing endpoints
src/routes/professorRoutes.js - Aulas routes · Lesson and class endpoints
src/routes/aulasRoutes.js - Video routes · Video-related endpoints
src/routes/videoRoutes.js - Auth ctrl · Handles auth request orchestration
src/routes/Controllers/authControllers.js - Professor ctrl · Handles professor workflows
src/routes/Controllers/professorController.js
Domain
Core business concepts
- User · Account and identity model
src/domain/User.js - Curso · Course model
src/domain/Curso.js - Materia · Subject model
src/domain/Materia.js - Atividade · Activity model
src/domain/Atividade.js - Progresso · Progress tracking model
src/domain/Progresso.js - Schemas · Shared domain validation and shaping rules
src/domain/schemas.js
Data
Persistence and schema bootstrapping
- User DAO · User persistence module
src/database/UserDataAcess.js - Curso DAO · Course persistence module
src/database/CursoDataAcess.js - Materia DAO · Subject persistence module
src/database/MateriaDataAcess.js - Atividade DAO · Activity persistence module
src/database/AtividadeDataAcess.js - Lesson progress · Per-lesson progress persistence
src/database/LessonProgressDataAccess.js - Curso progress · Course progress persistence
src/database/ProgressoCurso.js - DB init SQL · Startup SQL scripts that create tables
src/database/init/CreateTable_User.sql
Connections 36
- 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