# edwinsebastian-crypto/spp architecture

> Architecture diagram of the GitHub repository edwinsebastian-crypto/spp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edwinsebastian-crypto/spp
- Repository: https://github.com/edwinsebastian-crypto/spp

## Overview

SPP is a pedagogical-practice platform: users manage placements, activities and evidence, then tutors and students conduct evaluations and directors review outcomes and accreditation reports. The React client talks to the Express monolith, which owns practice-domain workflows and persistence; it delegates evaluation to a separate FastAPI service and notification delivery to an Express service. The README documents these service boundaries and storage integrations. Some subsystem internals are unsampled, so their nodes follow documented capabilities and their edges are limited to documented relationships or shown imports.

Main entry points: [`spp_practicas/src/routes/index.js`](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/routes/index.js) (Express routes), [`servicio_notificaciones/src/services/dispatcher.service.js`](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/services/dispatcher.service.js) (Idempotent mail dispatcher), [`spp_practicas/frontend/src/components/activities/ActivitiesAndEvidencesApp.jsx`](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/components/activities/ActivitiesAndEvidencesApp.jsx) (Practice and evaluation UI), [`spp_practicas/frontend/src/core/api.js`](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/core/api.js) (HTTP API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_ui["Practice and evaluation UI"]
  node_director_ui["Director dashboards"]
  node_ui_entry["React entry point<br/>[main.jsx]"]
  node_api_client["HTTP API client<br/>[api.js]"]
end

subgraph group_monolith["Practice monolith"]
  node_monolith_routes["Express routes<br/>[index.js]"]
  node_controllers["Domain controllers"]
  node_practice_services["Practice and report services"]
  node_evidence_service["Evidence management"]
  node_repositories["Domain repositories"]
  node_monolith_app["Monolith HTTP app<br/>[app.js]"]
  node_eval_gateway["Evaluation gateway"]
  node_notification_gateway["Notification gateway"]
end

subgraph group_evaluation["Evaluation service"]
  node_eval_api["Evaluation API<br/>[main.py]"]
  node_eval_routes["Tutor, student, director APIs"]
  node_eval_domain["Question and evaluation workflows<br/>[calificacion.py]"]
  node_evidence_client["Practice evidence client"]
  node_generation["AI question generation<br/>[generador.py]"]
end

subgraph group_notifications["Notification service"]
  node_notif_app["Notification HTTP app<br/>[app.js]"]
  node_notif_dispatch["Idempotent mail dispatcher"]
  node_notif_jobs["Scheduled notification jobs<br/>[jobs.service.js]"]
  node_mailer["Email delivery<br/>[mailer.js]"]
end

subgraph group_persistence["Persistence and integrations"]
  node_eval_db[("Evaluation database<br/>[database.py]")]
  node_practice_db[("Practice data store<br/>[postgres.js]")]
  node_file_storage["Evidence file storage<br/>[file-storage.js]"]
  node_notif_db[("Notification queue and history<br/>[mongo.js]")]
end

node_users(("Students, tutors, directors"))

node_users -->|"use"| node_ui
node_ui_entry -->|"mounts"| node_ui
node_ui_entry -->|"mounts"| node_director_ui
node_ui -->|"requests data"| node_api_client
node_director_ui -->|"requests data"| node_api_client
node_api_client -->|"HTTP requests"| node_monolith_routes
node_monolith_app -->|"registers"| node_monolith_routes
node_monolith_routes -->|"routes to"| node_controllers
node_controllers -.->|"delegates to"| node_practice_services
node_practice_services -->|"reads and writes"| node_repositories
node_evidence_service -.->|"stores files"| node_file_storage
node_repositories -->|"queries"| node_practice_db
node_eval_gateway -->|"secure proxy"| node_eval_api
node_notification_gateway -->|"sends events"| node_notif_app
node_eval_api -->|"registers"| node_eval_routes
node_eval_routes -.->|"invokes"| node_eval_domain
node_eval_domain -->|"persists results"| node_eval_db
node_generation -.->|"supports evaluation"| node_eval_domain
node_evidence_client -->|"fetches evidence"| node_monolith_routes
node_notif_app -.->|"serves dispatch"| node_notif_dispatch
node_notif_dispatch -->|"queues and updates"| node_notif_db
node_notif_jobs -.->|"reads queue"| node_notif_db
node_notif_dispatch -->|"delivers email"| node_mailer

click node_ui "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/components/activities/ActivitiesAndEvidencesApp.jsx"
click node_director_ui "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/components/director/DirectorEvaluationsDashboardApp.jsx"
click node_ui_entry "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/main.jsx"
click node_api_client "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/core/api.js"
click node_monolith_routes "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/routes/index.js"
click node_controllers "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/controllers/practice.controller.js"
click node_practice_services "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/services/practice.service.js"
click node_evidence_service "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/services/evidence.service.js"
click node_repositories "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/repositories/practice.repository.js"
click node_monolith_app "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/app.js"
click node_eval_gateway "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/services/evaluation-gateway.service.js"
click node_notification_gateway "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/infrastructure/notification-service.js"
click node_eval_api "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/main.py"
click node_eval_routes "https://github.com/edwinsebastian-crypto/spp/tree/master/servicio_evaluacion/backend/app/routers"
click node_eval_domain "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/services/calificacion.py"
click node_evidence_client "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/services/evidencias_client.py"
click node_generation "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/services/generador.py"
click node_eval_db "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/database.py"
click node_practice_db "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/infrastructure/postgres.js"
click node_file_storage "https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/infrastructure/file-storage.js"
click node_notif_app "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/app.js"
click node_notif_dispatch "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/services/dispatcher.service.js"
click node_notif_jobs "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/services/jobs.service.js"
click node_notif_db "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/infrastructure/mongo.js"
click node_mailer "https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/infrastructure/mailer.js"

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_ui,node_director_ui,node_ui_entry,node_api_client toneBlue
class node_monolith_routes,node_controllers,node_practice_services,node_evidence_service,node_repositories,node_monolith_app,node_eval_gateway,node_notification_gateway toneAmber
class node_eval_api,node_eval_routes,node_eval_domain,node_evidence_client,node_generation toneMint
class node_notif_app,node_notif_dispatch,node_notif_jobs,node_mailer toneRose
class node_eval_db,node_practice_db,node_file_storage,node_notif_db,node_users toneIndigo
```

## Components

### React client

- [Practice and evaluation UI](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/components/activities/ActivitiesAndEvidencesApp.jsx): `spp_practicas/frontend/src/components/activities/ActivitiesAndEvidencesApp.jsx`
- [Director dashboards](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/components/director/DirectorEvaluationsDashboardApp.jsx): `spp_practicas/frontend/src/components/director/DirectorEvaluationsDashboardApp.jsx`
- [React entry point](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/main.jsx): `spp_practicas/frontend/src/main.jsx`
- [HTTP API client](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/frontend/src/core/api.js): `spp_practicas/frontend/src/core/api.js`

### Practice monolith

- [Express routes](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/routes/index.js): `spp_practicas/src/routes/index.js`
- [Domain controllers](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/controllers/practice.controller.js): `spp_practicas/src/controllers/practice.controller.js`
- [Practice and report services](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/services/practice.service.js): `spp_practicas/src/services/practice.service.js`
- [Evidence management](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/services/evidence.service.js): `spp_practicas/src/services/evidence.service.js`
- [Domain repositories](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/repositories/practice.repository.js): `spp_practicas/src/repositories/practice.repository.js`
- [Monolith HTTP app](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/app.js): `spp_practicas/src/app.js`
- [Evaluation gateway](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/services/evaluation-gateway.service.js): `spp_practicas/src/services/evaluation-gateway.service.js`
- [Notification gateway](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/infrastructure/notification-service.js): `spp_practicas/src/infrastructure/notification-service.js`

### Evaluation service

- [Evaluation API](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/main.py): `servicio_evaluacion/backend/app/main.py`
- [Tutor, student, director APIs](https://github.com/edwinsebastian-crypto/spp/tree/master/servicio_evaluacion/backend/app/routers): `servicio_evaluacion/backend/app/routers`
- [Question and evaluation workflows](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/services/calificacion.py): `servicio_evaluacion/backend/app/services/calificacion.py`
- [Practice evidence client](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/services/evidencias_client.py): `servicio_evaluacion/backend/app/services/evidencias_client.py`
- [AI question generation](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/services/generador.py): `servicio_evaluacion/backend/app/services/generador.py`

### Notification service

- [Notification HTTP app](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/app.js): `servicio_notificaciones/src/app.js`
- [Idempotent mail dispatcher](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/services/dispatcher.service.js): `servicio_notificaciones/src/services/dispatcher.service.js`
- [Scheduled notification jobs](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/services/jobs.service.js): `servicio_notificaciones/src/services/jobs.service.js`
- [Email delivery](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/infrastructure/mailer.js): `servicio_notificaciones/src/infrastructure/mailer.js`

### Persistence and integrations

- [Evaluation database](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_evaluacion/backend/app/database.py): `servicio_evaluacion/backend/app/database.py`
- [Practice data store](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/infrastructure/postgres.js): `spp_practicas/src/infrastructure/postgres.js`
- [Evidence file storage](https://github.com/edwinsebastian-crypto/spp/blob/master/spp_practicas/src/infrastructure/file-storage.js): `spp_practicas/src/infrastructure/file-storage.js`
- [Notification queue and history](https://github.com/edwinsebastian-crypto/spp/blob/master/servicio_notificaciones/src/infrastructure/mongo.js): `servicio_notificaciones/src/infrastructure/mongo.js`

### Other components

- **Students, tutors, directors**

## Connections

- Students, tutors, directors → Practice and evaluation UI: use (evidence: `README.md`)
- React entry point → Practice and evaluation UI: mounts (evidence: `spp_practicas/frontend/src/main.jsx`)
- React entry point → Director dashboards: mounts (evidence: `spp_practicas/frontend/src/main.jsx`)
- Practice and evaluation UI → HTTP API client: requests data (evidence: `spp_practicas/frontend/src/components/activities/ActivitiesAndEvidencesApp.jsx`)
- Director dashboards → HTTP API client: requests data (evidence: `spp_practicas/frontend/src/components/director/DirectorEvaluationsDashboardApp.jsx`)
- HTTP API client → Express routes: HTTP requests (evidence: `README.md`)
- Monolith HTTP app → Express routes: registers (evidence: `spp_practicas/src/app.js`)
- Express routes → Domain controllers: routes to
- Domain controllers → Practice and report services: delegates to
- Practice and report services → Domain repositories: reads and writes (evidence: `README.md`)
- Evidence management → Evidence file storage: stores files
- Domain repositories → Practice data store: queries (evidence: `README.md`)
- Evaluation gateway → Evaluation API: secure proxy (evidence: `README.md`)
- Notification gateway → Notification HTTP app: sends events (evidence: `README.md`)
- Evaluation API → Tutor, student, director APIs: registers (evidence: `servicio_evaluacion/backend/app/main.py`)
- Tutor, student, director APIs → Question and evaluation workflows: invokes (evidence: `servicio_evaluacion/backend/app/routers/estudiante.py`)
- Question and evaluation workflows → Evaluation database: persists results (evidence: `README.md`)
- AI question generation → Question and evaluation workflows: supports evaluation
- Practice evidence client → Express routes: fetches evidence (evidence: `servicio_evaluacion/backend/app/services/evidencias_client.py`)
- Notification HTTP app → Idempotent mail dispatcher: serves dispatch
- Idempotent mail dispatcher → Notification queue and history: queues and updates (evidence: `README.md`)
- Scheduled notification jobs → Notification queue and history: reads queue
- Idempotent mail dispatcher → Email delivery: delivers email (evidence: `README.md`)
