# salaheddine-hadraoui/kestro architecture

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

- Interactive diagram: https://gitdiagram.com/salaheddine-hadraoui/kestro
- Repository: https://github.com/salaheddine-hadraoui/kestro

## Overview

Kestro is a SOC operations and investigation platform: analysts triage a shared alert queue, create and work cases, attach evidence and hypotheses, and resolve cases with an auditable record. Leads also manage users, playbooks, and organization-wide knowledge. The graph reflects the modular Next.js/NestJS application in the tree, while the README describes the intended product workflow. Several service implementations and UI action paths were not excerpted, so their internal links are omitted; the web-to-API boundary is supported by the API client excerpt.

Main entry points: [`apps/api/src/app.module.ts`](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/app.module.ts) (Nest application), [`apps/api/src/cases/cases.controller.ts`](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/cases/cases.controller.ts) (Case workflow), [`apps/web/lib/server/api-client.ts`](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/web/lib/server/api-client.ts) (Authenticated API client), [`apps/api/src/auth/auth.controller.ts`](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/auth/auth.controller.ts) (JWT authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspace"]
  node_workspace["Workspace UI"]
  node_web_features["Web feature services"]
  node_api_client["Authenticated API client<br/>[api-client.ts]"]
  node_auth_web["Web auth<br/>[service.ts]"]
end

subgraph group_api["API workflows"]
  node_alerts["Alert queue"]
  node_cases["Case workflow"]
  node_evidence["Evidence files"]
  node_investigations["Hypotheses"]
  node_timeline["Case timeline"]
  node_case_knowledge["Case knowledge links"]
  node_knowledge["Knowledge library"]
  node_playbooks["Playbooks"]
  node_users["User administration"]
  node_api_root["Nest application<br/>[app.module.ts]"]
end

subgraph group_auth["Identity and access"]
  node_auth_api["JWT authentication<br/>[auth.controller.ts]"]
  node_auth_service["Token and session service<br/>[auth.service.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma["Prisma data access<br/>[prisma.service.ts]"]
  node_postgres[("PostgreSQL")]
end

node_analyst(("SOC analyst"))

node_analyst -->|"uses"| node_workspace
node_workspace -.->|"invokes"| node_web_features
node_web_features -->|"calls"| node_api_client
node_auth_web -->|"calls"| node_api_client
node_api_client -->|"sends REST requests"| node_auth_api
node_auth_api -->|"delegates"| node_auth_service
node_auth_service -->|"reads and writes"| node_prisma
node_prisma -.->|"persists data"| node_postgres
node_api_root -->|"registers module"| node_alerts
node_api_root -->|"registers module"| node_cases
node_alerts -.->|"feeds case work"| node_cases
node_cases -->|"anchors evidence"| node_evidence
node_cases -->|"anchors hypotheses"| node_investigations
node_cases -.->|"records activity"| node_timeline
node_cases -.->|"links references"| node_case_knowledge
node_cases -.->|"references content"| node_knowledge
node_analyst -.->|"uses"| node_playbooks
node_analyst -.->|"administers"| node_users
node_api_root -->|"registers module"| node_auth_api
node_api_root -->|"registers module"| node_knowledge
node_api_root -->|"registers module"| node_playbooks
node_api_root -->|"registers module"| node_timeline
node_api_root -->|"registers module"| node_case_knowledge
node_api_root -->|"registers module"| node_users
node_api_root -->|"registers module"| node_prisma

click node_workspace "https://github.com/salaheddine-hadraoui/kestro/tree/main/apps/web/app/(workspace)"
click node_web_features "https://github.com/salaheddine-hadraoui/kestro/tree/main/apps/web/features"
click node_api_client "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/web/lib/server/api-client.ts"
click node_auth_web "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/web/features/auth/service.ts"
click node_alerts "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/alerts/alerts.controller.ts"
click node_cases "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/cases/cases.controller.ts"
click node_evidence "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/evidence/evidence.controller.ts"
click node_investigations "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/investigations/investigations.controller.ts"
click node_timeline "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/timeline/timeline.controller.ts"
click node_case_knowledge "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/case-knowledge/case-knowledge.controller.ts"
click node_knowledge "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/knowledge/knowledge.controller.ts"
click node_playbooks "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/playbooks/playbooks.controller.ts"
click node_users "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/users/users.controller.ts"
click node_auth_api "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/auth/auth.service.ts"
click node_prisma "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/prisma/prisma.service.ts"
click node_api_root "https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/app.module.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_workspace,node_web_features,node_api_client,node_auth_web toneBlue
class node_alerts,node_cases,node_evidence,node_investigations,node_timeline,node_case_knowledge,node_knowledge,node_playbooks,node_users,node_api_root toneAmber
class node_auth_api,node_auth_service toneMint
class node_prisma,node_postgres toneRose
class node_analyst toneIndigo
```

## Components

### Web workspace

- [Workspace UI](https://github.com/salaheddine-hadraoui/kestro/tree/main/apps/web/app/(workspace)): `apps/web/app/(workspace)`
- [Web feature services](https://github.com/salaheddine-hadraoui/kestro/tree/main/apps/web/features): `apps/web/features`
- [Authenticated API client](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/web/lib/server/api-client.ts): `apps/web/lib/server/api-client.ts`
- [Web auth](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/web/features/auth/service.ts): `apps/web/features/auth/service.ts`

### API workflows

- [Alert queue](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/alerts/alerts.controller.ts): `apps/api/src/alerts/alerts.controller.ts`
- [Case workflow](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/cases/cases.controller.ts): `apps/api/src/cases/cases.controller.ts`
- [Evidence files](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/evidence/evidence.controller.ts): `apps/api/src/evidence/evidence.controller.ts`
- [Hypotheses](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/investigations/investigations.controller.ts): `apps/api/src/investigations/investigations.controller.ts`
- [Case timeline](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/timeline/timeline.controller.ts): `apps/api/src/timeline/timeline.controller.ts`
- [Case knowledge links](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/case-knowledge/case-knowledge.controller.ts): `apps/api/src/case-knowledge/case-knowledge.controller.ts`
- [Knowledge library](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/knowledge/knowledge.controller.ts): `apps/api/src/knowledge/knowledge.controller.ts`
- [Playbooks](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/playbooks/playbooks.controller.ts): `apps/api/src/playbooks/playbooks.controller.ts`
- [User administration](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/users/users.controller.ts): `apps/api/src/users/users.controller.ts`
- [Nest application](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`

### Identity and access

- [JWT authentication](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/auth/auth.controller.ts): `apps/api/src/auth/auth.controller.ts`
- [Token and session service](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/auth/auth.service.ts): `apps/api/src/auth/auth.service.ts`

### Persistence

- [Prisma data access](https://github.com/salaheddine-hadraoui/kestro/blob/main/apps/api/src/prisma/prisma.service.ts): `apps/api/src/prisma/prisma.service.ts`
- **PostgreSQL**

### Other components

- **SOC analyst**

## Connections

- SOC analyst → Workspace UI: uses (evidence: `README.md`)
- Workspace UI → Web feature services: invokes
- Web feature services → Authenticated API client: calls (evidence: `apps/web/features/cases/service.ts`)
- Web auth → Authenticated API client: calls (evidence: `apps/web/features/auth/service.ts`)
- Authenticated API client → JWT authentication: sends REST requests (evidence: `apps/web/lib/server/api-client.ts`)
- JWT authentication → Token and session service: delegates (evidence: `apps/api/src/auth/auth.controller.ts`)
- Token and session service → Prisma data access: reads and writes (evidence: `apps/api/src/auth/auth.service.ts`)
- Prisma data access → PostgreSQL: persists data
- Nest application → Alert queue: registers module (evidence: `apps/api/src/app.module.ts`)
- Nest application → Case workflow: registers module (evidence: `apps/api/src/app.module.ts`)
- Alert queue → Case workflow: feeds case work (evidence: `README.md`)
- Case workflow → Evidence files: anchors evidence (evidence: `apps/api/src/evidence/evidence.controller.ts`)
- Case workflow → Hypotheses: anchors hypotheses (evidence: `apps/api/src/investigations/investigations.controller.ts`)
- Case workflow → Case timeline: records activity (evidence: `README.md`)
- Case workflow → Case knowledge links: links references
- Case workflow → Knowledge library: references content (evidence: `README.md`)
- SOC analyst → Playbooks: uses
- SOC analyst → User administration: administers
- Nest application → JWT authentication: registers module (evidence: `apps/api/src/app.module.ts`)
- Nest application → Knowledge library: registers module (evidence: `apps/api/src/app.module.ts`)
- Nest application → Playbooks: registers module (evidence: `apps/api/src/app.module.ts`)
- Nest application → Case timeline: registers module (evidence: `apps/api/src/app.module.ts`)
- Nest application → Case knowledge links: registers module (evidence: `apps/api/src/app.module.ts`)
- Nest application → User administration: registers module (evidence: `apps/api/src/app.module.ts`)
- Nest application → Prisma data access: registers module (evidence: `apps/api/src/app.module.ts`)