# jm-ortega/piedrazul-agendamiento-citas architecture

> Architecture diagram of the GitHub repository jm-ortega/piedrazul-agendamiento-citas, 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/jm-ortega/piedrazul-agendamiento-citas
- Repository: https://github.com/jm-ortega/piedrazul-agendamiento-citas

## Overview

Piedra Azul is a role-based clinic appointment platform. Patients or clinic staff initiate scheduling through the Angular SPA; the Spring API provides appointment availability and booking, while doctors and administrators use related agenda, management, and reporting capabilities. The backend is a modular monolith with PostgreSQL persistence and locally validated Keycloak-issued JWTs. The README documents the main product capabilities and system boundaries; sampled source also shows role-aware frontend navigation and patient, doctor, and notification service responsibilities, but does not expose enough wiring to assert most internal calls.

Main entry points: [`backend/src/main/java/co/edu/unicauca/piedrazul/backend`](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend) (REST API), [`frontend/src/app`](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/frontend/src/app) (Role-based SPA), [`backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/api/AppointmentController.java`](https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/api/AppointmentController.java) (Appointment API), [`backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/application`](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/application) (Scheduling rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Role-based SPA"]
  node_routes["Role routes<br/>[app.routes.ts]"]
  node_booking["Booking UI state"]
end

subgraph group_appointments["Appointment lifecycle"]
  node_api["REST API"]
  node_appointment_api["Appointment API"]
  node_appointment_rules["Scheduling rules"]
  node_appointment_store[("Appointment data")]
end

subgraph group_clinic["Clinic operations"]
  node_patient_ops["Patient management"]
  node_doctor_ops["Doctor and schedules<br/>[DoctorService.java]"]
  node_user_ops["User administration<br/>[UserService.java]"]
  node_reporting["Reports and statistics"]
  node_audit["Audit queries"]
end

subgraph group_platform["Identity and messaging"]
  node_verification["Account verification"]
  node_notifications["Notifications"]
  node_keycloak["Keycloak identity"]
  node_postgres[("PostgreSQL")]
end

node_patient(("Patient"))
node_clinic_staff(("Clinic staff"))

node_patient -->|"uses"| node_frontend
node_clinic_staff -->|"uses"| node_frontend
node_frontend -->|"signs in via OIDC"| node_keycloak
node_frontend -->|"sends bearer requests"| node_api
node_frontend -->|"loads role routes"| node_routes
node_frontend -.->|"supports booking"| node_booking
node_api -->|"exposes appointments"| node_appointment_api
node_api -->|"persists business data"| node_postgres
node_api -->|"validates JWT keys"| node_keycloak
node_appointment_api -.->|"handles scheduling"| node_appointment_rules
node_appointment_rules -.->|"stores appointments"| node_appointment_store
node_api -->|"supports patient workflows"| node_patient_ops
node_api -->|"supports doctor workflows"| node_doctor_ops
node_api -->|"supports administration"| node_user_ops
node_api -->|"provides reports"| node_reporting
node_api -->|"provides audit events"| node_audit
node_api -->|"verifies account links"| node_verification
node_api -->|"sends reminders"| node_notifications

click node_frontend "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/frontend/src/app"
click node_routes "https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/frontend/src/app/app.routes.ts"
click node_booking "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/frontend/src/app/features/appointment/services"
click node_api "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend"
click node_appointment_api "https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/api/AppointmentController.java"
click node_appointment_rules "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/application"
click node_appointment_store "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/persistence"
click node_patient_ops "https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/patients/application/PatientService.java"
click node_doctor_ops "https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/doctors/application/DoctorService.java"
click node_user_ops "https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/user/application/UserService.java"
click node_reporting "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/report/application"
click node_audit "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/audit/application"
click node_verification "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/verification"
click node_notifications "https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/notifications/application/NotificationDispatcherService.java"
click node_keycloak "https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/infra/keycloak"

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_frontend,node_routes,node_booking toneBlue
class node_api,node_appointment_api,node_appointment_rules,node_appointment_store toneAmber
class node_patient_ops,node_doctor_ops,node_user_ops,node_reporting,node_audit toneMint
class node_verification,node_notifications,node_keycloak,node_postgres toneRose
class node_patient,node_clinic_staff toneIndigo
```

## Components

### Web experience

- [Role-based SPA](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/frontend/src/app): `frontend/src/app`
- [Role routes](https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/frontend/src/app/app.routes.ts): `frontend/src/app/app.routes.ts`
- [Booking UI state](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/frontend/src/app/features/appointment/services): `frontend/src/app/features/appointment/services`

### Appointment lifecycle

- [REST API](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend): `backend/src/main/java/co/edu/unicauca/piedrazul/backend`
- [Appointment API](https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/api/AppointmentController.java): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/api/AppointmentController.java`
- [Scheduling rules](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/application): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/application`
- [Appointment data](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/persistence): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/infrastructure/persistence`

### Clinic operations

- [Patient management](https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/patients/application/PatientService.java): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/patients/application/PatientService.java`
- [Doctor and schedules](https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/doctors/application/DoctorService.java): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/doctors/application/DoctorService.java`
- [User administration](https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/user/application/UserService.java): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/user/application/UserService.java`
- [Reports and statistics](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/report/application): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/report/application`
- [Audit queries](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/audit/application): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/audit/application`

### Identity and messaging

- [Account verification](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/verification): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/verification`
- [Notifications](https://github.com/jm-ortega/piedrazul-agendamiento-citas/blob/main/backend/src/main/java/co/edu/unicauca/piedrazul/backend/notifications/application/NotificationDispatcherService.java): `backend/src/main/java/co/edu/unicauca/piedrazul/backend/notifications/application/NotificationDispatcherService.java`
- [Keycloak identity](https://github.com/jm-ortega/piedrazul-agendamiento-citas/tree/main/infra/keycloak): `infra/keycloak`
- **PostgreSQL**

### Other components

- **Patient**
- **Clinic staff**

## Connections

- Patient → Role-based SPA: uses (evidence: `README.md`)
- Clinic staff → Role-based SPA: uses (evidence: `README.md`)
- Role-based SPA → Keycloak identity: signs in via OIDC (evidence: `README.md`)
- Role-based SPA → REST API: sends bearer requests (evidence: `README.md`)
- Role-based SPA → Role routes: loads role routes (evidence: `frontend/src/app/app.routes.ts`)
- Role-based SPA → Booking UI state: supports booking (evidence: `frontend/src/app/features/appointment/services/bookingState.service.ts`)
- REST API → Appointment API: exposes appointments (evidence: `README.md`)
- REST API → PostgreSQL: persists business data (evidence: `README.md`)
- REST API → Keycloak identity: validates JWT keys (evidence: `README.md`)
- Appointment API → Scheduling rules: handles scheduling
- Scheduling rules → Appointment data: stores appointments (evidence: `backend/src/main/java/co/edu/unicauca/piedrazul/backend/appointment/application/AppointmentSchedulingService.java`)
- REST API → Patient management: supports patient workflows (evidence: `README.md`)
- REST API → Doctor and schedules: supports doctor workflows (evidence: `README.md`)
- REST API → User administration: supports administration (evidence: `README.md`)
- REST API → Reports and statistics: provides reports (evidence: `README.md`)
- REST API → Audit queries: provides audit events (evidence: `README.md`)
- REST API → Account verification: verifies account links (evidence: `README.md`)
- REST API → Notifications: sends reminders (evidence: `README.md`)
