# nossairaa/auditsphere architecture

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

- Interactive diagram: https://gitdiagram.com/nossairaa/auditsphere
- Repository: https://github.com/nossairaa/auditsphere

## Overview

AuditSphere is an internal-audit platform spanning mission planning, risk/control evidence, findings and independent validation, then corrective actions through verification and closure. Users work through the Next.js BFF, which preserves tokens server-side before calling the gateway and services. The graph follows documented service responsibilities and sampled calls; several links between domain stages and unsampled capabilities are documented in the README and are shown with README evidence. Detailed browser-to-BFF and gateway routing beyond the README are not sampled.

Main entry points: [`services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java`](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java) (Mission lifecycle), [`services/remediation-service/src/main/java/com/auditsphere/remediation/Remediation.java`](https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/Remediation.java) (Corrective actions), [`services/api-gateway/src/main/java/com/auditsphere/gateway/GatewayApplication.java`](https://github.com/nossairaa/auditsphere/blob/main/services/api-gateway/src/main/java/com/auditsphere/gateway/GatewayApplication.java) (API gateway), [`services/notification-service/src/main/java/com/auditsphere/notification/NotificationController.java`](https://github.com/nossairaa/auditsphere/blob/main/services/notification-service/src/main/java/com/auditsphere/notification/NotificationController.java) (Notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Next.js workspace"]
  node_bff["BFF API"]
  node_auth["OIDC session<br/>[auth.ts]"]
end

subgraph group_audit["Audit service"]
  node_mission["Mission lifecycle"]
  node_missiondata[("Mission records<br/>[Mission.java]")]
  node_program["Audit programs"]
  node_directory["Auditor directory"]
  node_controls["Controls and evidence"]
  node_evidence[("Evidence object store<br/>[EvidenceStore.java]")]
  node_findings["Findings"]
  node_actionlog[("Audit history")]
  node_review["Independent review"]
end

subgraph group_remediation["Remediation service"]
  node_remediation["Corrective actions<br/>[Remediation.java]"]
  node_actioncontroller["Action management"]
  node_followup["Follow-up verification"]
  node_attachments["Action attachments"]
  node_attachmentstore[("Attachment store")]
end

subgraph group_async["Events and workflow"]
  node_reviewworker["Review worker<br/>[ReviewWorker.java]"]
  node_temporal["Temporal"]
  node_assignment["Assignment events"]
  node_kafka["Kafka"]
  node_notifications["Notifications"]
  node_stream["Live notification stream"]
end

subgraph group_platform["API and identity"]
  node_gateway["API gateway"]
  node_keycloak["Keycloak"]
  node_postgres[("Service PostgreSQL")]
  node_s3[("Private S3 storage")]
end

node_user(("Audit team"))

node_user -->|"uses"| node_webapp
node_webapp -->|"requests"| node_bff
node_bff -->|"checks session"| node_auth
node_auth -->|"OIDC login"| node_keycloak
node_bff -->|"forwards JWT"| node_gateway
node_gateway -->|"routes requests"| node_mission
node_gateway -->|"routes requests"| node_remediation
node_gateway -->|"routes requests"| node_notifications
node_mission -->|"reads and writes"| node_missiondata
node_mission -->|"validates users"| node_directory
node_program -->|"reads and writes"| node_missiondata
node_controls -->|"stores evidence"| node_evidence
node_mission -.->|"includes controls"| node_controls
node_mission -.->|"governs findings"| node_findings
node_findings -.->|"records changes"| node_actionlog
node_mission -->|"records actions"| node_actionlog
node_mission -.->|"submits review"| node_review
node_review -->|"starts durable workflow"| node_temporal
node_reviewworker -->|"runs workflows"| node_temporal
node_findings -.->|"synchronizes issues"| node_remediation
node_actioncontroller -->|"uses action scope"| node_remediation
node_followup -->|"checks scope"| node_remediation
node_attachments -->|"authorizes action"| node_remediation
node_attachments -->|"reads and writes"| node_attachmentstore
node_mission -.->|"records outbox"| node_assignment
node_assignment -.->|"publishes events"| node_kafka
node_kafka -.->|"delivers events"| node_notifications
node_notifications -->|"subscribes clients"| node_stream
node_mission -.->|"persists domain state"| node_postgres
node_remediation -.->|"persists domain state"| node_postgres
node_notifications -.->|"reads notification state"| node_postgres
node_evidence -.->|"stores objects"| node_s3
node_attachmentstore -.->|"stores objects"| node_s3

click node_webapp "https://github.com/nossairaa/auditsphere/tree/main/apps/web/src/app"
click node_bff "https://github.com/nossairaa/auditsphere/tree/main/apps/web/src/app/api"
click node_auth "https://github.com/nossairaa/auditsphere/blob/main/apps/web/src/lib/auth.ts"
click node_gateway "https://github.com/nossairaa/auditsphere/blob/main/services/api-gateway/src/main/java/com/auditsphere/gateway/GatewayApplication.java"
click node_mission "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java"
click node_missiondata "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/Mission.java"
click node_program "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/AuditProgramController.java"
click node_directory "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/AuditorDirectory.java"
click node_controls "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/ControlEvidenceController.java"
click node_evidence "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/EvidenceStore.java"
click node_findings "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/FindingController.java"
click node_actionlog "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/MissionActionLog.java"
click node_review "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/workflow/ReviewWorkflow.java"
click node_reviewworker "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/workflow/ReviewWorker.java"
click node_remediation "https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/Remediation.java"
click node_actioncontroller "https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/ActionController.java"
click node_followup "https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/FollowUpController.java"
click node_attachments "https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentController.java"
click node_attachmentstore "https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentStore.java"
click node_assignment "https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/AssignmentOutbox.java"
click node_notifications "https://github.com/nossairaa/auditsphere/blob/main/services/notification-service/src/main/java/com/auditsphere/notification/NotificationController.java"
click node_stream "https://github.com/nossairaa/auditsphere/blob/main/services/notification-service/src/main/java/com/auditsphere/notification/NotificationStream.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_webapp,node_bff,node_auth toneBlue
class node_mission,node_missiondata,node_program,node_directory,node_controls,node_evidence,node_findings,node_actionlog,node_review toneAmber
class node_remediation,node_actioncontroller,node_followup,node_attachments,node_attachmentstore toneMint
class node_reviewworker,node_temporal,node_assignment,node_kafka,node_notifications,node_stream toneRose
class node_gateway,node_keycloak,node_postgres,node_s3,node_user toneIndigo
```

## Components

### Web application

- [Next.js workspace](https://github.com/nossairaa/auditsphere/tree/main/apps/web/src/app): `apps/web/src/app`
- [BFF API](https://github.com/nossairaa/auditsphere/tree/main/apps/web/src/app/api): `apps/web/src/app/api`
- [OIDC session](https://github.com/nossairaa/auditsphere/blob/main/apps/web/src/lib/auth.ts): `apps/web/src/lib/auth.ts`

### Audit service

- [Mission lifecycle](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java): `services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java`
- [Mission records](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/Mission.java): `services/audit-service/src/main/java/com/auditsphere/audit/Mission.java`
- [Audit programs](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/AuditProgramController.java): `services/audit-service/src/main/java/com/auditsphere/audit/AuditProgramController.java`
- [Auditor directory](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/AuditorDirectory.java): `services/audit-service/src/main/java/com/auditsphere/audit/AuditorDirectory.java`
- [Controls and evidence](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/ControlEvidenceController.java): `services/audit-service/src/main/java/com/auditsphere/audit/ControlEvidenceController.java`
- [Evidence object store](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/EvidenceStore.java): `services/audit-service/src/main/java/com/auditsphere/audit/EvidenceStore.java`
- [Findings](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/FindingController.java): `services/audit-service/src/main/java/com/auditsphere/audit/FindingController.java`
- [Audit history](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/MissionActionLog.java): `services/audit-service/src/main/java/com/auditsphere/audit/MissionActionLog.java`
- [Independent review](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/workflow/ReviewWorkflow.java): `services/audit-service/src/main/java/com/auditsphere/audit/workflow/ReviewWorkflow.java`

### Remediation service

- [Corrective actions](https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/Remediation.java): `services/remediation-service/src/main/java/com/auditsphere/remediation/Remediation.java`
- [Action management](https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/ActionController.java): `services/remediation-service/src/main/java/com/auditsphere/remediation/ActionController.java`
- [Follow-up verification](https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/FollowUpController.java): `services/remediation-service/src/main/java/com/auditsphere/remediation/FollowUpController.java`
- [Action attachments](https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentController.java): `services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentController.java`
- [Attachment store](https://github.com/nossairaa/auditsphere/blob/main/services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentStore.java): `services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentStore.java`

### Events and workflow

- [Review worker](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/workflow/ReviewWorker.java): `services/audit-service/src/main/java/com/auditsphere/audit/workflow/ReviewWorker.java`
- **Temporal**
- [Assignment events](https://github.com/nossairaa/auditsphere/blob/main/services/audit-service/src/main/java/com/auditsphere/audit/AssignmentOutbox.java): `services/audit-service/src/main/java/com/auditsphere/audit/AssignmentOutbox.java`
- **Kafka**
- [Notifications](https://github.com/nossairaa/auditsphere/blob/main/services/notification-service/src/main/java/com/auditsphere/notification/NotificationController.java): `services/notification-service/src/main/java/com/auditsphere/notification/NotificationController.java`
- [Live notification stream](https://github.com/nossairaa/auditsphere/blob/main/services/notification-service/src/main/java/com/auditsphere/notification/NotificationStream.java): `services/notification-service/src/main/java/com/auditsphere/notification/NotificationStream.java`

### API and identity

- [API gateway](https://github.com/nossairaa/auditsphere/blob/main/services/api-gateway/src/main/java/com/auditsphere/gateway/GatewayApplication.java): `services/api-gateway/src/main/java/com/auditsphere/gateway/GatewayApplication.java`
- **Keycloak**
- **Service PostgreSQL**
- **Private S3 storage**

### Other components

- **Audit team**

## Connections

- Audit team → Next.js workspace: uses (evidence: `README.md`)
- Next.js workspace → BFF API: requests (evidence: `README.md`)
- BFF API → OIDC session: checks session (evidence: `apps/web/src/app/api/session/route.ts`)
- OIDC session → Keycloak: OIDC login (evidence: `README.md`)
- BFF API → API gateway: forwards JWT (evidence: `README.md`)
- API gateway → Mission lifecycle: routes requests (evidence: `README.md`)
- API gateway → Corrective actions: routes requests (evidence: `README.md`)
- API gateway → Notifications: routes requests (evidence: `README.md`)
- Mission lifecycle → Mission records: reads and writes (evidence: `services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java`)
- Mission lifecycle → Auditor directory: validates users (evidence: `services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java`)
- Audit programs → Mission records: reads and writes (evidence: `services/audit-service/src/main/java/com/auditsphere/audit/AuditProgramController.java`)
- Controls and evidence → Evidence object store: stores evidence (evidence: `services/audit-service/src/main/java/com/auditsphere/audit/ControlEvidenceController.java`)
- Mission lifecycle → Controls and evidence: includes controls (evidence: `README.md`)
- Mission lifecycle → Findings: governs findings (evidence: `README.md`)
- Findings → Audit history: records changes (evidence: `README.md`)
- Mission lifecycle → Audit history: records actions (evidence: `services/audit-service/src/main/java/com/auditsphere/audit/MissionController.java`)
- Mission lifecycle → Independent review: submits review (evidence: `README.md`)
- Independent review → Temporal: starts durable workflow (evidence: `README.md`)
- Review worker → Temporal: runs workflows (evidence: `services/audit-service/src/main/java/com/auditsphere/audit/workflow/ReviewWorker.java`)
- Findings → Corrective actions: synchronizes issues (evidence: `README.md`)
- Action management → Corrective actions: uses action scope (evidence: `services/remediation-service/src/main/java/com/auditsphere/remediation/ActionController.java`)
- Follow-up verification → Corrective actions: checks scope (evidence: `services/remediation-service/src/main/java/com/auditsphere/remediation/FollowUpController.java`)
- Action attachments → Corrective actions: authorizes action (evidence: `services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentController.java`)
- Action attachments → Attachment store: reads and writes (evidence: `services/remediation-service/src/main/java/com/auditsphere/remediation/AttachmentController.java`)
- Mission lifecycle → Assignment events: records outbox (evidence: `README.md`)
- Assignment events → Kafka: publishes events (evidence: `README.md`)
- Kafka → Notifications: delivers events (evidence: `README.md`)
- Notifications → Live notification stream: subscribes clients (evidence: `services/notification-service/src/main/java/com/auditsphere/notification/NotificationController.java`)
- Mission lifecycle → Service PostgreSQL: persists domain state (evidence: `README.md`)
- Corrective actions → Service PostgreSQL: persists domain state (evidence: `README.md`)
- Notifications → Service PostgreSQL: reads notification state (evidence: `README.md`)
- Evidence object store → Private S3 storage: stores objects (evidence: `README.md`)
- Attachment store → Private S3 storage: stores objects (evidence: `README.md`)
