# stagsz/normetta architecture

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

- Interactive diagram: https://gitdiagram.com/stagsz/normetta
- Repository: https://github.com/stagsz/normetta

## Overview

Normetta is an ISO 9001 quality-management and audit platform. Users configure standards and assessments, record responses and evidence, review compliance, then manage non-conformities and corrective actions; dashboards and reports support oversight. The graph highlights the frontend, API routing and domain modules, and persistent data. Sampled code confirms API startup and routing, standards and corrective-action service calls, and authentication and GDPR data access; some unsampled domain wiring is therefore left unspecified.

Main entry points: [`backend/src/config/database.ts`](https://github.com/stagsz/normetta/blob/main/backend/src/config/database.ts) (Application database), [`frontend/src/app`](https://github.com/stagsz/normetta/tree/main/frontend/src/app) (Web application), [`frontend/src/lib/api.ts`](https://github.com/stagsz/normetta/blob/main/frontend/src/lib/api.ts) (API client), [`backend/src/routes`](https://github.com/stagsz/normetta/tree/main/backend/src/routes) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_web["Web application"]
  node_assessment_ui["Assessment workspace"]
  node_ncr_ui["Findings and actions"]
  node_dashboard_ui["Dashboard and reports"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_server["Express API<br/>[index.ts]"]
  node_routes["API routes"]
  node_auth["Authentication<br/>[authService.ts]"]
end

subgraph group_quality["Quality workflows"]
  node_assessment_routes["Assessment routes"]
  node_assessment_controller["Assessment controller"]
  node_standards_controller["Standards controller"]
  node_standards_service["Standards service"]
  node_response_service["Assessment responses<br/>[responseService.ts]"]
  node_evidence_service["Evidence management<br/>[evidenceService.ts]"]
  node_report_service["Reports<br/>[reportService.ts]"]
  node_ncr_routes["Non-conformity routes"]
  node_ncr_controller["Non-conformity controller"]
  node_action_controller["Corrective actions"]
  node_dashboard_service["Dashboard service"]
  node_agent["Root-cause assistant"]
end

subgraph group_data["Data and integrations"]
  node_db[("Application database<br/>[database.ts]")]
  node_email["Email delivery<br/>[emailService.ts]"]
end

node_user(("Quality team"))
node_mail_provider["Email provider"]

node_user -->|"uses"| node_web
node_web -->|"opens"| node_assessment_ui
node_web -->|"opens"| node_ncr_ui
node_web -->|"opens"| node_dashboard_ui
node_assessment_ui -->|"requests data"| node_api_client
node_ncr_ui -->|"requests data"| node_api_client
node_dashboard_ui -->|"requests data"| node_api_client
node_api_client -->|"sends requests"| node_server
node_server -->|"dispatches"| node_routes
node_routes -->|"mounts"| node_assessment_routes
node_assessment_routes -->|"invokes"| node_assessment_controller
node_routes -->|"mounts"| node_ncr_routes
node_ncr_routes -->|"invokes"| node_ncr_controller
node_ncr_routes -->|"invokes chat"| node_agent
node_standards_controller -->|"calls"| node_standards_service
node_action_controller -.->|"reads and writes"| node_db
node_auth -->|"reads and writes"| node_db
node_auth -->|"requests delivery"| node_email
node_email -.->|"sends mail"| node_mail_provider
node_dashboard_service -.->|"reads"| node_db
node_response_service -.->|"reads and writes"| node_db
node_evidence_service -.->|"reads and writes"| node_db
node_report_service -.->|"reads"| node_db

click node_web "https://github.com/stagsz/normetta/tree/main/frontend/src/app"
click node_assessment_ui "https://github.com/stagsz/normetta/tree/main/frontend/src/app/(dashboard)/assessments"
click node_ncr_ui "https://github.com/stagsz/normetta/tree/main/frontend/src/app/(dashboard)/non-conformities"
click node_dashboard_ui "https://github.com/stagsz/normetta/tree/main/frontend/src/app/(dashboard)"
click node_api_client "https://github.com/stagsz/normetta/blob/main/frontend/src/lib/api.ts"
click node_server "https://github.com/stagsz/normetta/blob/main/backend/src/index.ts"
click node_routes "https://github.com/stagsz/normetta/tree/main/backend/src/routes"
click node_auth "https://github.com/stagsz/normetta/blob/main/backend/src/services/authService.ts"
click node_assessment_routes "https://github.com/stagsz/normetta/blob/main/backend/src/routes/assessmentRoutes.ts"
click node_assessment_controller "https://github.com/stagsz/normetta/blob/main/backend/src/controllers/assessmentController.ts"
click node_standards_controller "https://github.com/stagsz/normetta/blob/main/backend/src/controllers/standardsController.ts"
click node_standards_service "https://github.com/stagsz/normetta/blob/main/backend/src/services/standardsService.ts"
click node_response_service "https://github.com/stagsz/normetta/blob/main/backend/src/services/responseService.ts"
click node_evidence_service "https://github.com/stagsz/normetta/blob/main/backend/src/services/evidenceService.ts"
click node_report_service "https://github.com/stagsz/normetta/blob/main/backend/src/services/reportService.ts"
click node_ncr_routes "https://github.com/stagsz/normetta/blob/main/backend/src/routes/nonConformityRoutes.ts"
click node_ncr_controller "https://github.com/stagsz/normetta/blob/main/backend/src/controllers/nonConformityController.ts"
click node_action_controller "https://github.com/stagsz/normetta/blob/main/backend/src/controllers/correctiveActionController.ts"
click node_dashboard_service "https://github.com/stagsz/normetta/blob/main/backend/src/services/dashboardService.ts"
click node_db "https://github.com/stagsz/normetta/blob/main/backend/src/config/database.ts"
click node_agent "https://github.com/stagsz/normetta/blob/main/backend/src/services/rootCauseAgentService.ts"
click node_email "https://github.com/stagsz/normetta/blob/main/backend/src/services/emailService.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_web,node_assessment_ui,node_ncr_ui,node_dashboard_ui,node_api_client toneBlue
class node_server,node_routes,node_auth toneAmber
class node_assessment_routes,node_assessment_controller,node_standards_controller,node_standards_service,node_response_service,node_evidence_service,node_report_service,node_ncr_routes,node_ncr_controller,node_action_controller,node_dashboard_service,node_agent toneMint
class node_db,node_email toneRose
class node_user,node_mail_provider toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/stagsz/normetta/tree/main/frontend/src/app): `frontend/src/app`
- [Assessment workspace](https://github.com/stagsz/normetta/tree/main/frontend/src/app/(dashboard)/assessments): `frontend/src/app/(dashboard)/assessments`
- [Findings and actions](https://github.com/stagsz/normetta/tree/main/frontend/src/app/(dashboard)/non-conformities): `frontend/src/app/(dashboard)/non-conformities`
- [Dashboard and reports](https://github.com/stagsz/normetta/tree/main/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`
- [API client](https://github.com/stagsz/normetta/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and access

- [Express API](https://github.com/stagsz/normetta/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [API routes](https://github.com/stagsz/normetta/tree/main/backend/src/routes): `backend/src/routes`
- [Authentication](https://github.com/stagsz/normetta/blob/main/backend/src/services/authService.ts): `backend/src/services/authService.ts`

### Quality workflows

- [Assessment routes](https://github.com/stagsz/normetta/blob/main/backend/src/routes/assessmentRoutes.ts): `backend/src/routes/assessmentRoutes.ts`
- [Assessment controller](https://github.com/stagsz/normetta/blob/main/backend/src/controllers/assessmentController.ts): `backend/src/controllers/assessmentController.ts`
- [Standards controller](https://github.com/stagsz/normetta/blob/main/backend/src/controllers/standardsController.ts): `backend/src/controllers/standardsController.ts`
- [Standards service](https://github.com/stagsz/normetta/blob/main/backend/src/services/standardsService.ts): `backend/src/services/standardsService.ts`
- [Assessment responses](https://github.com/stagsz/normetta/blob/main/backend/src/services/responseService.ts): `backend/src/services/responseService.ts`
- [Evidence management](https://github.com/stagsz/normetta/blob/main/backend/src/services/evidenceService.ts): `backend/src/services/evidenceService.ts`
- [Reports](https://github.com/stagsz/normetta/blob/main/backend/src/services/reportService.ts): `backend/src/services/reportService.ts`
- [Non-conformity routes](https://github.com/stagsz/normetta/blob/main/backend/src/routes/nonConformityRoutes.ts): `backend/src/routes/nonConformityRoutes.ts`
- [Non-conformity controller](https://github.com/stagsz/normetta/blob/main/backend/src/controllers/nonConformityController.ts): `backend/src/controllers/nonConformityController.ts`
- [Corrective actions](https://github.com/stagsz/normetta/blob/main/backend/src/controllers/correctiveActionController.ts): `backend/src/controllers/correctiveActionController.ts`
- [Dashboard service](https://github.com/stagsz/normetta/blob/main/backend/src/services/dashboardService.ts): `backend/src/services/dashboardService.ts`
- [Root-cause assistant](https://github.com/stagsz/normetta/blob/main/backend/src/services/rootCauseAgentService.ts): `backend/src/services/rootCauseAgentService.ts`

### Data and integrations

- [Application database](https://github.com/stagsz/normetta/blob/main/backend/src/config/database.ts): `backend/src/config/database.ts`
- [Email delivery](https://github.com/stagsz/normetta/blob/main/backend/src/services/emailService.ts): `backend/src/services/emailService.ts`

### Other components

- **Quality team**
- **Email provider**

## Connections

- Quality team → Web application: uses
- Web application → Assessment workspace: opens
- Web application → Findings and actions: opens
- Web application → Dashboard and reports: opens
- Assessment workspace → API client: requests data
- Findings and actions → API client: requests data
- Dashboard and reports → API client: requests data
- API client → Express API: sends requests
- Express API → API routes: dispatches
- API routes → Assessment routes: mounts
- Assessment routes → Assessment controller: invokes
- API routes → Non-conformity routes: mounts
- Non-conformity routes → Non-conformity controller: invokes
- Non-conformity routes → Root-cause assistant: invokes chat
- Standards controller → Standards service: calls
- Corrective actions → Application database: reads and writes
- Authentication → Application database: reads and writes
- Authentication → Email delivery: requests delivery
- Email delivery → Email provider: sends mail
- Dashboard service → Application database: reads
- Assessment responses → Application database: reads and writes
- Evidence management → Application database: reads and writes
- Reports → Application database: reads