# ruthieruth/cleartrace architecture

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

- Interactive diagram: https://gitdiagram.com/ruthieruth/cleartrace
- Repository: https://github.com/ruthieruth/cleartrace

## Overview

ClearTrace is a role-controlled registry for managing person and offense records, with agency searches, company record requests and central approval, and superadmin oversight. The principal workflow is an authorized user accessing a role-specific dashboard, then searching or maintaining records; companies can request a record and privileged staff can update its status. Backend controllers delegate domain operations to services, which use Prisma for persistence. The README describes audit trails and planned tenant isolation and duplicate review; source excerpts do not establish their implementation or frontend-to-endpoint wiring.

Main entry points: [`backend/src/prisma.service.ts`](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/prisma.service.ts) (Prisma data access), [`backend/src/common/guards/jwt-auth.guards.ts`](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/common/guards/jwt-auth.guards.ts) (JWT guard), [`backend/src/common/guards/roles.guard.ts`](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/common/guards/roles.guard.ts) (Role guard), [`backend/src/persons/persons.controller.ts`](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/persons/persons.controller.ts) (Person endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Role-based portal"]
  node_agency_ui["Agency dashboard"]
  node_officer_ui["Data officer dashboard"]
  node_admin_ui["Superadmin dashboard"]
  node_company_ui["Company portal<br/>[page.tsx]"]
  node_request_form["Request form<br/>[RequestForm.tsx]"]
  node_results_ui["Record results"]
end

subgraph group_access["Identity and access"]
  node_user_api["User endpoints"]
  node_user_service["User management<br/>[users.service.ts]"]
  node_auth_guard["JWT guard<br/>[jwt-auth.guards.ts]"]
  node_roles_guard["Role guard<br/>[roles.guard.ts]"]
end

subgraph group_registry["Registry operations"]
  node_person_api["Person endpoints"]
  node_person_service["Person search<br/>[persons.service.ts]"]
  node_offense_api["Offense endpoints"]
  node_offense_service["Offense records"]
  node_company_api["Company endpoints"]
  node_company_service["Company management"]
end

subgraph group_oversight["Requests and oversight"]
  node_request_api["Request endpoints"]
  node_request_service["Request lifecycle"]
  node_audit_api["Audit log endpoints"]
  node_audit_service["Audit log queries"]
end

subgraph group_storage["Persistence and identity providers"]
  node_prisma["Prisma data access<br/>[prisma.service.ts]"]
  node_postgres[("Registry database")]
  node_clerk["Clerk identity"]
end

node_user(("Registry users"))

node_user -->|"uses"| node_agency_ui
node_user -->|"uses"| node_officer_ui
node_user -->|"uses"| node_admin_ui
node_user -->|"uses"| node_company_ui
node_company_ui -->|"opens"| node_request_form
node_agency_ui -->|"views"| node_results_ui
node_officer_ui -->|"views"| node_results_ui
node_user_api -->|"delegates"| node_user_service
node_user_service -->|"reads and writes"| node_prisma
node_user_service -->|"creates accounts"| node_clerk
node_person_api -->|"delegates"| node_person_service
node_person_api -->|"looks up user"| node_prisma
node_person_service -->|"searches records"| node_prisma
node_offense_api -->|"delegates"| node_offense_service
node_offense_api -->|"looks up user"| node_prisma
node_offense_service -->|"reads and writes"| node_prisma
node_company_api -->|"delegates"| node_company_service
node_company_service -->|"reads and writes"| node_prisma
node_request_api -->|"delegates"| node_request_service
node_request_api -->|"looks up requester"| node_prisma
node_request_service -->|"reads and writes"| node_prisma
node_audit_api -->|"delegates"| node_audit_service
node_audit_service -->|"queries logs"| node_prisma
node_prisma -->|"persists data"| node_postgres
node_person_api -->|"guards requests"| node_auth_guard
node_offense_api -->|"guards requests"| node_auth_guard
node_request_api -->|"guards requests"| node_auth_guard
node_user_api -->|"guards requests"| node_auth_guard
node_company_api -->|"guards requests"| node_auth_guard
node_audit_api -->|"guards requests"| node_auth_guard
node_person_api -->|"checks roles"| node_roles_guard
node_offense_api -->|"checks roles"| node_roles_guard
node_request_api -->|"checks roles"| node_roles_guard
node_user_api -->|"checks roles"| node_roles_guard
node_company_api -->|"checks roles"| node_roles_guard
node_audit_api -->|"checks roles"| node_roles_guard

click node_agency_ui "https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/(AgencyDashboard)/AgencyDashboard.tsx"
click node_officer_ui "https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/(DataOfficerDashboard)/DataOfficerDashboard.tsx"
click node_admin_ui "https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/(SuperAdminDashboard)/SuperAdminDashboard.tsx"
click node_company_ui "https://github.com/ruthieruth/cleartrace/blob/main/frontend/app/(company)/company/page.tsx"
click node_request_form "https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/RequestForm.tsx"
click node_results_ui "https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/sharedAcrossApp/RequestedResults.tsx"
click node_user_api "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/users/users.controller.ts"
click node_user_service "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/users/users.service.ts"
click node_auth_guard "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/common/guards/jwt-auth.guards.ts"
click node_roles_guard "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/common/guards/roles.guard.ts"
click node_person_api "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/persons/persons.controller.ts"
click node_person_service "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/persons/persons.service.ts"
click node_offense_api "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/offenses/offenses.controller.ts"
click node_offense_service "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/offenses/offenses.service.ts"
click node_company_api "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/companies/companies.controller.ts"
click node_company_service "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/companies/companies.service.ts"
click node_request_api "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/requests/requests.controller.ts"
click node_request_service "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/requests/requests.service.ts"
click node_audit_api "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/audit-logs/audit-logs.controller.ts"
click node_audit_service "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/audit-logs/audit-logs.service.ts"
click node_prisma "https://github.com/ruthieruth/cleartrace/blob/main/backend/src/prisma.service.ts"

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_agency_ui,node_officer_ui,node_admin_ui,node_company_ui,node_request_form,node_results_ui,node_user toneBlue
class node_user_api,node_user_service,node_auth_guard,node_roles_guard toneAmber
class node_person_api,node_person_service,node_offense_api,node_offense_service,node_company_api,node_company_service toneMint
class node_request_api,node_request_service,node_audit_api,node_audit_service toneRose
class node_prisma,node_postgres,node_clerk toneIndigo
```

## Components

### Role-based portal

- [Agency dashboard](https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/(AgencyDashboard)/AgencyDashboard.tsx): `frontend/Components/(AgencyDashboard)/AgencyDashboard.tsx`
- [Data officer dashboard](https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/(DataOfficerDashboard)/DataOfficerDashboard.tsx): `frontend/Components/(DataOfficerDashboard)/DataOfficerDashboard.tsx`
- [Superadmin dashboard](https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/(SuperAdminDashboard)/SuperAdminDashboard.tsx): `frontend/Components/(SuperAdminDashboard)/SuperAdminDashboard.tsx`
- [Company portal](https://github.com/ruthieruth/cleartrace/blob/main/frontend/app/(company)/company/page.tsx): `frontend/app/(company)/company/page.tsx`
- [Request form](https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/RequestForm.tsx): `frontend/Components/RequestForm.tsx`
- [Record results](https://github.com/ruthieruth/cleartrace/blob/main/frontend/Components/sharedAcrossApp/RequestedResults.tsx): `frontend/Components/sharedAcrossApp/RequestedResults.tsx`

### Identity and access

- [User endpoints](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/users/users.controller.ts): `backend/src/users/users.controller.ts`
- [User management](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/users/users.service.ts): `backend/src/users/users.service.ts`
- [JWT guard](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/common/guards/jwt-auth.guards.ts): `backend/src/common/guards/jwt-auth.guards.ts`
- [Role guard](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/common/guards/roles.guard.ts): `backend/src/common/guards/roles.guard.ts`

### Registry operations

- [Person endpoints](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/persons/persons.controller.ts): `backend/src/persons/persons.controller.ts`
- [Person search](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/persons/persons.service.ts): `backend/src/persons/persons.service.ts`
- [Offense endpoints](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/offenses/offenses.controller.ts): `backend/src/offenses/offenses.controller.ts`
- [Offense records](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/offenses/offenses.service.ts): `backend/src/offenses/offenses.service.ts`
- [Company endpoints](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/companies/companies.controller.ts): `backend/src/companies/companies.controller.ts`
- [Company management](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/companies/companies.service.ts): `backend/src/companies/companies.service.ts`

### Requests and oversight

- [Request endpoints](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/requests/requests.controller.ts): `backend/src/requests/requests.controller.ts`
- [Request lifecycle](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/requests/requests.service.ts): `backend/src/requests/requests.service.ts`
- [Audit log endpoints](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/audit-logs/audit-logs.controller.ts): `backend/src/audit-logs/audit-logs.controller.ts`
- [Audit log queries](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/audit-logs/audit-logs.service.ts): `backend/src/audit-logs/audit-logs.service.ts`

### Persistence and identity providers

- [Prisma data access](https://github.com/ruthieruth/cleartrace/blob/main/backend/src/prisma.service.ts): `backend/src/prisma.service.ts`
- **Registry database**
- **Clerk identity**

### Other components

- **Registry users**

## Connections

- Registry users → Agency dashboard: uses
- Registry users → Data officer dashboard: uses
- Registry users → Superadmin dashboard: uses
- Registry users → Company portal: uses
- Company portal → Request form: opens
- Agency dashboard → Record results: views
- Data officer dashboard → Record results: views
- User endpoints → User management: delegates
- User management → Prisma data access: reads and writes
- User management → Clerk identity: creates accounts
- Person endpoints → Person search: delegates
- Person endpoints → Prisma data access: looks up user
- Person search → Prisma data access: searches records
- Offense endpoints → Offense records: delegates
- Offense endpoints → Prisma data access: looks up user
- Offense records → Prisma data access: reads and writes
- Company endpoints → Company management: delegates
- Company management → Prisma data access: reads and writes
- Request endpoints → Request lifecycle: delegates
- Request endpoints → Prisma data access: looks up requester
- Request lifecycle → Prisma data access: reads and writes
- Audit log endpoints → Audit log queries: delegates
- Audit log queries → Prisma data access: queries logs
- Prisma data access → Registry database: persists data
- Person endpoints → JWT guard: guards requests
- Offense endpoints → JWT guard: guards requests
- Request endpoints → JWT guard: guards requests
- User endpoints → JWT guard: guards requests
- Company endpoints → JWT guard: guards requests
- Audit log endpoints → JWT guard: guards requests
- Person endpoints → Role guard: checks roles
- Offense endpoints → Role guard: checks roles
- Request endpoints → Role guard: checks roles
- User endpoints → Role guard: checks roles
- Company endpoints → Role guard: checks roles
- Audit log endpoints → Role guard: checks roles