# cibertec-courses/matricula-api architecture

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

- Interactive diagram: https://gitdiagram.com/cibertec-courses/matricula-api
- Repository: https://github.com/cibertec-courses/matricula-api

## Overview

matricula-api is a role-protected REST API for academic enrollment. Users authenticate, then students or administrators can quote and register courses in an open period, pay or cancel enrollments, and later view records; instructors record grades. The README also documents catalog and people administration, account/session security, and payment/history capabilities. Edges are limited to relationships visible in excerpts or README statements; unsampled controller and service wiring is represented conservatively, with the README supporting the broader domain branches.

Main entry points: [`src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java) (Enrollment service), [`src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java`](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java) (Student records), [`src/main/java/pe/edu/cibertec/matricula_api/service/CursoService.java`](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/CursoService.java) (Course catalog), [`src/main/java/pe/edu/cibertec/matricula_api/repository/MatriculaRepository.java`](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/repository/MatriculaRepository.java) (Enrollment store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity and access"]
  node_auth_api["Auth endpoints"]
  node_auth_service["Authentication service<br/>[AuthService.java]"]
  node_security["JWT security"]
  node_users["User accounts"]
end

subgraph group_catalog["Academic catalog"]
  node_catalog_api["Catalog endpoints"]
  node_courses["Course catalog<br/>[CursoService.java]"]
  node_careers["Career management"]
  node_period_api["Period endpoints"]
  node_periods["Academic periods"]
end

subgraph group_enrollment["Enrollment lifecycle"]
  node_enroll_api["Enrollment endpoints"]
  node_enrollments["Enrollment service"]
  node_pricing["Enrollment pricing"]
  node_payments_api["Payment endpoints"]
  node_payments["Payment records<br/>[PagoService.java]"]
end

subgraph group_records["Student and staff records"]
  node_students_api["Student endpoints"]
  node_students["Student records<br/>[AlumnoService.java]"]
  node_staff_api["Staff endpoints"]
  node_staff["Instructor records"]
end

subgraph group_persistence["Persistence layer"]
  node_matricula_store[("Enrollment store")]
  node_course_store[("Course store")]
  node_error_handling["API error mapping"]
  node_domain_models["Academic domain<br/>[Matricula.java]"]
end

node_client(("API caller"))

node_client -->|"requests login"| node_auth_api
node_auth_api -->|"delegates auth"| node_auth_service
node_client -->|"requests enrollment"| node_enroll_api
node_enroll_api -->|"delegates enrollment"| node_enrollments
node_enrollments -->|"calculates quote"| node_pricing
node_enrollments -->|"loads student"| node_students
node_enrollments -->|"checks course"| node_courses
node_enrollments -->|"checks open period"| node_periods
node_enrollments -->|"saves enrollments"| node_matricula_store
node_enrollments -->|"creates payment"| node_payments
node_client -->|"browses catalog"| node_catalog_api
node_catalog_api -->|"delegates course operations"| node_courses
node_courses -->|"queries courses"| node_course_store
node_courses -->|"checks enrollment use"| node_matricula_store
node_client -->|"manages periods"| node_period_api
node_period_api -->|"delegates period operations"| node_periods
node_periods -->|"annuls pending enrollments"| node_matricula_store
node_client -->|"requests student records"| node_students_api
node_students_api -->|"delegates student operations"| node_students
node_students -->|"resolves career"| node_careers
node_students -->|"creates account"| node_users
node_students -->|"checks enrollments"| node_matricula_store
node_client -->|"manages instructors"| node_staff_api
node_staff_api -->|"delegates staff operations"| node_staff
node_client -->|"requests payment records"| node_payments_api
node_payments_api -->|"delegates payment queries"| node_payments
node_security -.->|"validates sessions"| node_auth_service
node_enroll_api -.->|"returns API errors"| node_error_handling

click node_auth_api "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/AuthController.java"
click node_auth_service "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/AuthService.java"
click node_security "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/security/SecurityConfig.java"
click node_users "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/UsuarioService.java"
click node_catalog_api "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/CursoController.java"
click node_courses "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/CursoService.java"
click node_careers "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/CarreraService.java"
click node_period_api "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/PeriodoController.java"
click node_periods "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/PeriodoService.java"
click node_enroll_api "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/MatriculaController.java"
click node_enrollments "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java"
click node_pricing "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/CalculadoraMatricula.java"
click node_payments_api "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/PagoController.java"
click node_payments "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/PagoService.java"
click node_students_api "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/AlumnoController.java"
click node_students "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java"
click node_staff_api "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/DocenteController.java"
click node_staff "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/DocenteService.java"
click node_matricula_store "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/repository/MatriculaRepository.java"
click node_course_store "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/repository/CursoRepository.java"
click node_error_handling "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/exception/GlobalExceptionHandler.java"
click node_domain_models "https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/model/Matricula.java"

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_auth_api,node_auth_service,node_security,node_users toneBlue
class node_catalog_api,node_courses,node_careers,node_period_api,node_periods toneAmber
class node_enroll_api,node_enrollments,node_pricing,node_payments_api,node_payments,node_client toneMint
class node_students_api,node_students,node_staff_api,node_staff toneRose
class node_matricula_store,node_course_store,node_error_handling,node_domain_models toneIndigo
```

## Components

### Identity and access

- [Auth endpoints](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/AuthController.java): `src/main/java/pe/edu/cibertec/matricula_api/controller/AuthController.java`
- [Authentication service](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/AuthService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/AuthService.java`
- [JWT security](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/security/SecurityConfig.java): `src/main/java/pe/edu/cibertec/matricula_api/security/SecurityConfig.java`
- [User accounts](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/UsuarioService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/UsuarioService.java`

### Academic catalog

- [Catalog endpoints](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/CursoController.java): `src/main/java/pe/edu/cibertec/matricula_api/controller/CursoController.java`
- [Course catalog](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/CursoService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/CursoService.java`
- [Career management](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/CarreraService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/CarreraService.java`
- [Period endpoints](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/PeriodoController.java): `src/main/java/pe/edu/cibertec/matricula_api/controller/PeriodoController.java`
- [Academic periods](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/PeriodoService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/PeriodoService.java`

### Enrollment lifecycle

- [Enrollment endpoints](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/MatriculaController.java): `src/main/java/pe/edu/cibertec/matricula_api/controller/MatriculaController.java`
- [Enrollment service](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`
- [Enrollment pricing](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/CalculadoraMatricula.java): `src/main/java/pe/edu/cibertec/matricula_api/service/CalculadoraMatricula.java`
- [Payment endpoints](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/PagoController.java): `src/main/java/pe/edu/cibertec/matricula_api/controller/PagoController.java`
- [Payment records](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/PagoService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/PagoService.java`

### Student and staff records

- [Student endpoints](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/AlumnoController.java): `src/main/java/pe/edu/cibertec/matricula_api/controller/AlumnoController.java`
- [Student records](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java`
- [Staff endpoints](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/controller/DocenteController.java): `src/main/java/pe/edu/cibertec/matricula_api/controller/DocenteController.java`
- [Instructor records](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/service/DocenteService.java): `src/main/java/pe/edu/cibertec/matricula_api/service/DocenteService.java`

### Persistence layer

- [Enrollment store](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/repository/MatriculaRepository.java): `src/main/java/pe/edu/cibertec/matricula_api/repository/MatriculaRepository.java`
- [Course store](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/repository/CursoRepository.java): `src/main/java/pe/edu/cibertec/matricula_api/repository/CursoRepository.java`
- [API error mapping](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/exception/GlobalExceptionHandler.java): `src/main/java/pe/edu/cibertec/matricula_api/exception/GlobalExceptionHandler.java`
- [Academic domain](https://github.com/cibertec-courses/matricula-api/blob/main/src/main/java/pe/edu/cibertec/matricula_api/model/Matricula.java): `src/main/java/pe/edu/cibertec/matricula_api/model/Matricula.java`

### Other components

- **API caller**

## Connections

- API caller → Auth endpoints: requests login (evidence: `README.md`)
- Auth endpoints → Authentication service: delegates auth (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/AuthService.java`)
- API caller → Enrollment endpoints: requests enrollment (evidence: `README.md`)
- Enrollment endpoints → Enrollment service: delegates enrollment (evidence: `src/main/java/pe/edu/cibertec/matricula_api/controller/MatriculaController.java`)
- Enrollment service → Enrollment pricing: calculates quote (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`)
- Enrollment service → Student records: loads student (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`)
- Enrollment service → Course catalog: checks course (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`)
- Enrollment service → Academic periods: checks open period (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`)
- Enrollment service → Enrollment store: saves enrollments (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`)
- Enrollment service → Payment records: creates payment (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/MatriculaService.java`)
- API caller → Catalog endpoints: browses catalog (evidence: `README.md`)
- Catalog endpoints → Course catalog: delegates course operations (evidence: `src/main/java/pe/edu/cibertec/matricula_api/controller/CursoController.java`)
- Course catalog → Course store: queries courses (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/CursoService.java`)
- Course catalog → Enrollment store: checks enrollment use (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/CursoService.java`)
- API caller → Period endpoints: manages periods (evidence: `README.md`)
- Period endpoints → Academic periods: delegates period operations (evidence: `src/main/java/pe/edu/cibertec/matricula_api/controller/PeriodoController.java`)
- Academic periods → Enrollment store: annuls pending enrollments (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/PeriodoService.java`)
- API caller → Student endpoints: requests student records (evidence: `README.md`)
- Student endpoints → Student records: delegates student operations (evidence: `src/main/java/pe/edu/cibertec/matricula_api/controller/AlumnoController.java`)
- Student records → Career management: resolves career (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java`)
- Student records → User accounts: creates account (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java`)
- Student records → Enrollment store: checks enrollments (evidence: `src/main/java/pe/edu/cibertec/matricula_api/service/AlumnoService.java`)
- API caller → Staff endpoints: manages instructors (evidence: `README.md`)
- Staff endpoints → Instructor records: delegates staff operations (evidence: `README.md`)
- API caller → Payment endpoints: requests payment records (evidence: `README.md`)
- Payment endpoints → Payment records: delegates payment queries (evidence: `README.md`)
- JWT security → Authentication service: validates sessions (evidence: `README.md`)
- Enrollment endpoints → API error mapping: returns API errors (evidence: `README.md`)
