# joshrandomcodes/psa-digital-tracking-system architecture

> Architecture diagram of the GitHub repository joshrandomcodes/psa-digital-tracking-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshrandomcodes/psa-digital-tracking-system
- Repository: https://github.com/joshrandomcodes/psa-digital-tracking-system

## Overview

This is a PSA birth-certificate request, validation, and tracking application. Citizens register or sign in, submit a request, and track its status; requests are checked through the PhilSys and PhilCRIS integration boundaries, then handled by LCRO validation and PSA staff review. The React app calls an Express API, whose controllers read and update the MySQL-backed records. The README documents a cloud-hosted Aiven database. PhilSys verification is explicitly a stub, and the excerpts do not establish a live external registry connection.

Main entry points: [`client/src/App.jsx`](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/App.jsx) (Role-based App), [`client/src/services/api.js`](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/services/api.js) (API Client), [`server/src/config/db.js`](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/config/db.js) (MySQL Pool), [`server/src/server.js`](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/server.js) (Express Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Citizen and Staff UI"]
  node_app["Role-based App<br/>[App.jsx]"]
  node_authui["Authentication UI<br/>[AuthGateway.jsx]"]
  node_requestform["Request Form"]
  node_tracker["Live Tracker<br/>[LiveTracker.jsx]"]
  node_lcroui["LCRO Queue UI"]
  node_staffui["Staff Review UI"]
  node_api_client["API Client<br/>[api.js]"]
end

subgraph group_api["API and Workflow"]
  node_server["Express Routes<br/>[server.js]"]
  node_auth["Authentication<br/>[authController.js]"]
  node_requests["Request Processing"]
  node_lcro["LCRO Validation<br/>[lcroController.js]"]
  node_decision["Final Decision"]
end

subgraph group_integrations["Identity and Registry"]
  node_philsys["PhilSys Gateway<br/>[philsysGateway.js]"]
  node_philcris["PhilCRIS Adapter<br/>[philcrisAdapter.js]"]
end

subgraph group_data["Persistence"]
  node_mysql[("MySQL Pool<br/>[db.js]")]
  node_schema["Core Entities<br/>[schema.sql]"]
end

node_citizen(("Citizen"))
node_staff(("PSA staff"))
node_aiven[("Aiven MySQL")]
node_registry(("PSA Registries"))

node_citizen -->|"uses"| node_app
node_staff -->|"uses"| node_app
node_app -->|"renders"| node_authui
node_app -->|"renders"| node_requestform
node_app -->|"renders"| node_tracker
node_app -->|"renders"| node_lcroui
node_app -->|"renders"| node_staffui
node_authui -->|"auth calls"| node_api_client
node_requestform -->|"submits"| node_api_client
node_lcroui -->|"validates"| node_api_client
node_staffui -->|"sends decision"| node_api_client
node_app -->|"loads queues"| node_api_client
node_api_client -->|"HTTP requests"| node_server
node_server -->|"routes auth"| node_auth
node_server -->|"routes requests"| node_requests
node_server -->|"routes validation"| node_lcro
node_server -->|"routes decisions"| node_decision
node_requests -->|"verifies identity"| node_philsys
node_requests -->|"checks registry"| node_philcris
node_auth -->|"queries"| node_mysql
node_requests -->|"reads and writes"| node_mysql
node_lcro -->|"reads and writes"| node_mysql
node_decision -->|"updates records"| node_mysql
node_mysql -.->|"connects"| node_aiven
node_schema -.->|"defines entities"| node_mysql
node_philsys -.->|"potential integration"| node_registry
node_philcris -.->|"potential integration"| node_registry

click node_app "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/App.jsx"
click node_authui "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/AuthGateway.jsx"
click node_requestform "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/CitizenRequestForm.jsx"
click node_tracker "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/LiveTracker.jsx"
click node_lcroui "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/LcroValidationPanel.jsx"
click node_staffui "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/StaffReviewBoard.jsx"
click node_api_client "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/services/api.js"
click node_server "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/server.js"
click node_auth "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/authController.js"
click node_requests "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/requestController.js"
click node_lcro "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/lcroController.js"
click node_decision "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/psaStaffController.js"
click node_philsys "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/integrations/philsysGateway.js"
click node_philcris "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/integrations/philcrisAdapter.js"
click node_mysql "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/config/db.js"
click node_schema "https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/database/schema.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_app,node_authui,node_requestform,node_tracker,node_lcroui,node_staffui,node_api_client toneBlue
class node_server,node_auth,node_requests,node_lcro,node_decision,node_aiven toneAmber
class node_philsys,node_philcris toneMint
class node_mysql,node_schema toneRose
class node_citizen,node_staff,node_registry toneIndigo
```

## Components

### Citizen and Staff UI

- [Role-based App](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Authentication UI](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/AuthGateway.jsx): `client/src/components/AuthGateway.jsx`
- [Request Form](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/CitizenRequestForm.jsx): `client/src/components/CitizenRequestForm.jsx`
- [Live Tracker](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/LiveTracker.jsx): `client/src/components/LiveTracker.jsx`
- [LCRO Queue UI](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/LcroValidationPanel.jsx): `client/src/components/LcroValidationPanel.jsx`
- [Staff Review UI](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/components/StaffReviewBoard.jsx): `client/src/components/StaffReviewBoard.jsx`
- [API Client](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/client/src/services/api.js): `client/src/services/api.js`

### API and Workflow

- [Express Routes](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/server.js): `server/src/server.js`
- [Authentication](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/authController.js): `server/src/controllers/authController.js`
- [Request Processing](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/requestController.js): `server/src/controllers/requestController.js`
- [LCRO Validation](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/lcroController.js): `server/src/controllers/lcroController.js`
- [Final Decision](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/controllers/psaStaffController.js): `server/src/controllers/psaStaffController.js`

### Identity and Registry

- [PhilSys Gateway](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/integrations/philsysGateway.js): `server/src/integrations/philsysGateway.js`
- [PhilCRIS Adapter](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/integrations/philcrisAdapter.js): `server/src/integrations/philcrisAdapter.js`

### Persistence

- [MySQL Pool](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/server/src/config/db.js): `server/src/config/db.js`
- [Core Entities](https://github.com/joshrandomcodes/psa-digital-tracking-system/blob/main/database/schema.sql): `database/schema.sql`

### Other components

- **Citizen**
- **PSA staff**
- **Aiven MySQL**
- **PSA Registries**

## Connections

- Citizen → Role-based App: uses (evidence: `client/src/App.jsx`)
- PSA staff → Role-based App: uses (evidence: `client/src/App.jsx`)
- Role-based App → Authentication UI: renders (evidence: `client/src/App.jsx`)
- Role-based App → Request Form: renders (evidence: `client/src/App.jsx`)
- Role-based App → Live Tracker: renders (evidence: `client/src/App.jsx`)
- Role-based App → LCRO Queue UI: renders (evidence: `client/src/App.jsx`)
- Role-based App → Staff Review UI: renders (evidence: `client/src/App.jsx`)
- Authentication UI → API Client: auth calls (evidence: `client/src/components/AuthGateway.jsx`)
- Request Form → API Client: submits (evidence: `client/src/components/CitizenRequestForm.jsx`)
- LCRO Queue UI → API Client: validates (evidence: `client/src/components/LcroValidationPanel.jsx`)
- Staff Review UI → API Client: sends decision (evidence: `client/src/components/StaffReviewBoard.jsx`)
- Role-based App → API Client: loads queues (evidence: `client/src/App.jsx`)
- API Client → Express Routes: HTTP requests (evidence: `client/src/services/api.js`)
- Express Routes → Authentication: routes auth (evidence: `server/src/server.js`)
- Express Routes → Request Processing: routes requests (evidence: `server/src/server.js`)
- Express Routes → LCRO Validation: routes validation (evidence: `server/src/server.js`)
- Express Routes → Final Decision: routes decisions (evidence: `server/src/server.js`)
- Request Processing → PhilSys Gateway: verifies identity (evidence: `server/src/controllers/requestController.js`)
- Request Processing → PhilCRIS Adapter: checks registry (evidence: `server/src/controllers/requestController.js`)
- Authentication → MySQL Pool: queries (evidence: `server/src/controllers/authController.js`)
- Request Processing → MySQL Pool: reads and writes (evidence: `server/src/controllers/requestController.js`)
- LCRO Validation → MySQL Pool: reads and writes (evidence: `server/src/controllers/lcroController.js`)
- Final Decision → MySQL Pool: updates records (evidence: `server/src/controllers/psaStaffController.js`)
- MySQL Pool → Aiven MySQL: connects (evidence: `README.md`)
- Core Entities → MySQL Pool: defines entities (evidence: `README.md`)
- PhilSys Gateway → PSA Registries: potential integration
- PhilCRIS Adapter → PSA Registries: potential integration
