# ngynduc/forenotes architecture

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

- Interactive diagram: https://gitdiagram.com/ngynduc/forenotes
- Repository: https://github.com/ngynduc/forenotes

## Overview

Forenotes is a DFIR case notebook: responders manage incident evidence and work items, investigate relationships and MITRE ATT&CK mappings, then generate and export reports. The main path is user interaction in the web client through API routes into domain services and PostgreSQL; authorization and shared domain types support that path. Separate capabilities include dashboards, search, notifications, audit, and an optional MCP agent interface. The report service can call a distinct report-LLM service. Some subsystem connections are documented rather than excerpted, so the graph omits unverified calls.

Main entry points: [`src/server/routes/index.ts`](https://github.com/ngynduc/forenotes/blob/main/src/server/routes/index.ts) (API routes), [`src/server/app.ts`](https://github.com/ngynduc/forenotes/blob/main/src/server/app.ts) (HTTP application), [`src/server/services/reportService.ts`](https://github.com/ngynduc/forenotes/blob/main/src/server/services/reportService.ts) (Report generation), [`src/server/services/queryService.ts`](https://github.com/ngynduc/forenotes/blob/main/src/server/services/queryService.ts) (Hunt queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_web["Forenotes UI<br/>[App.tsx]"]
  node_client_pages["Workspaces"]
  node_client_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_api_app["HTTP application<br/>[app.ts]"]
  node_api_routes["API routes<br/>[index.ts]"]
  node_auth["Authentication<br/>[authService.ts]"]
  node_permissions["Authorization"]
end

subgraph group_response["Incident response"]
  node_incidents["Cases and incidents<br/>[incidentService.ts]"]
  node_findings["Findings and evidence<br/>[findingService.ts]"]
  node_tasks["Tasks and notes<br/>[taskService.ts]"]
  node_timeline["Timeline and indicators"]
  node_queries["Hunt queries<br/>[queryService.ts]"]
end

subgraph group_insight["Investigation and reporting"]
  node_dashboard["Dashboards"]
  node_search["Search<br/>[searchService.ts]"]
  node_graph["Investigation graph<br/>[graphBuilder.ts]"]
  node_mitre["MITRE matrix"]
  node_reports["Report generation<br/>[reportService.ts]"]
  node_pdf["PDF rendering"]
end

subgraph group_platform["State and integrations"]
  node_audit["Audit log<br/>[auditLogService.ts]"]
  node_notifications["Notifications"]
  node_database[("PostgreSQL<br/>[pool.ts]")]
  node_transaction["Request transactions<br/>[transaction.ts]"]
  node_domain["Shared domain types<br/>[domain.ts]"]
  node_report_types["Report contracts<br/>[reportTypes.ts]"]
  node_llm_client["Report LLM client"]
  node_mcp_handler["MCP HTTP interface<br/>[mcpHttpHandler.ts]"]
  node_mcp_tools["MCP tools"]
end

node_responder(("Responder"))
node_report_llm["Report LLM service<br/>[app.py]"]

node_responder -->|"uses"| node_web
node_web -.->|"renders"| node_client_pages
node_client_pages -.->|"requests"| node_client_api
node_api_app -->|"mounts"| node_api_routes
node_api_app -->|"wraps writes"| node_transaction
node_api_app -->|"routes MCP"| node_mcp_handler
node_api_routes -->|"authenticates"| node_auth
node_api_routes -->|"dispatches reports"| node_reports
node_api_routes -->|"dispatches queries"| node_queries
node_queries -->|"checks access"| node_permissions
node_queries -->|"records changes"| node_audit
node_api_routes -->|"dispatches findings"| node_findings
node_api_routes -->|"dispatches tasks"| node_tasks
node_api_routes -->|"builds matrix"| node_mitre
node_api_routes -.->|"builds graph"| node_graph
node_reports -->|"requests generation"| node_llm_client
node_reports -->|"renders PDF"| node_pdf
node_llm_client -->|"posts report context"| node_report_llm
node_mcp_handler -->|"registers tools"| node_mcp_tools
node_reports -->|"uses contracts"| node_report_types
node_api_app -->|"uses pool"| node_database
node_auth -->|"publishes state"| node_notifications

click node_web "https://github.com/ngynduc/forenotes/blob/main/src/client/src/App.tsx"
click node_client_pages "https://github.com/ngynduc/forenotes/tree/main/src/client/src/pages"
click node_client_api "https://github.com/ngynduc/forenotes/blob/main/src/client/src/lib/api.ts"
click node_api_app "https://github.com/ngynduc/forenotes/blob/main/src/server/app.ts"
click node_api_routes "https://github.com/ngynduc/forenotes/blob/main/src/server/routes/index.ts"
click node_auth "https://github.com/ngynduc/forenotes/blob/main/src/server/services/authService.ts"
click node_permissions "https://github.com/ngynduc/forenotes/blob/main/src/server/permissions/permissionService.ts"
click node_incidents "https://github.com/ngynduc/forenotes/blob/main/src/server/services/incidentService.ts"
click node_findings "https://github.com/ngynduc/forenotes/blob/main/src/server/services/findingService.ts"
click node_tasks "https://github.com/ngynduc/forenotes/blob/main/src/server/services/taskService.ts"
click node_timeline "https://github.com/ngynduc/forenotes/blob/main/src/server/services/timelineEventService.ts"
click node_queries "https://github.com/ngynduc/forenotes/blob/main/src/server/services/queryService.ts"
click node_dashboard "https://github.com/ngynduc/forenotes/blob/main/src/server/services/dashboardService.ts"
click node_search "https://github.com/ngynduc/forenotes/blob/main/src/server/services/searchService.ts"
click node_graph "https://github.com/ngynduc/forenotes/blob/main/src/server/graph/graphBuilder.ts"
click node_mitre "https://github.com/ngynduc/forenotes/blob/main/src/server/graph/mitreMatrixBuilder.ts"
click node_reports "https://github.com/ngynduc/forenotes/blob/main/src/server/services/reportService.ts"
click node_pdf "https://github.com/ngynduc/forenotes/blob/main/src/server/services/reportPdfRenderer.ts"
click node_audit "https://github.com/ngynduc/forenotes/blob/main/src/server/services/auditLogService.ts"
click node_notifications "https://github.com/ngynduc/forenotes/blob/main/src/server/services/notificationService.ts"
click node_database "https://github.com/ngynduc/forenotes/blob/main/src/server/db/pool.ts"
click node_transaction "https://github.com/ngynduc/forenotes/blob/main/src/server/db/transaction.ts"
click node_domain "https://github.com/ngynduc/forenotes/blob/main/src/shared/domain.ts"
click node_report_types "https://github.com/ngynduc/forenotes/blob/main/src/shared/reportTypes.ts"
click node_llm_client "https://github.com/ngynduc/forenotes/blob/main/src/server/services/litellmServiceClient.ts"
click node_report_llm "https://github.com/ngynduc/forenotes/blob/main/services/report-llm-service/app.py"
click node_mcp_handler "https://github.com/ngynduc/forenotes/blob/main/src/server/mcp/mcpHttpHandler.ts"
click node_mcp_tools "https://github.com/ngynduc/forenotes/blob/main/src/server/mcp/registerMcpTools.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_client_pages,node_client_api toneBlue
class node_api_app,node_api_routes,node_auth,node_permissions toneAmber
class node_incidents,node_findings,node_tasks,node_timeline,node_queries toneMint
class node_dashboard,node_search,node_graph,node_mitre,node_reports,node_pdf toneRose
class node_audit,node_notifications,node_database,node_transaction,node_domain,node_report_types,node_llm_client,node_mcp_handler,node_mcp_tools,node_responder toneIndigo
class node_report_llm toneTeal
```

## Components

### Web application

- [Forenotes UI](https://github.com/ngynduc/forenotes/blob/main/src/client/src/App.tsx): `src/client/src/App.tsx`
- [Workspaces](https://github.com/ngynduc/forenotes/tree/main/src/client/src/pages): `src/client/src/pages`
- [API client](https://github.com/ngynduc/forenotes/blob/main/src/client/src/lib/api.ts): `src/client/src/lib/api.ts`

### API and access

- [HTTP application](https://github.com/ngynduc/forenotes/blob/main/src/server/app.ts): `src/server/app.ts`
- [API routes](https://github.com/ngynduc/forenotes/blob/main/src/server/routes/index.ts): `src/server/routes/index.ts`
- [Authentication](https://github.com/ngynduc/forenotes/blob/main/src/server/services/authService.ts): `src/server/services/authService.ts`
- [Authorization](https://github.com/ngynduc/forenotes/blob/main/src/server/permissions/permissionService.ts): `src/server/permissions/permissionService.ts`

### Incident response

- [Cases and incidents](https://github.com/ngynduc/forenotes/blob/main/src/server/services/incidentService.ts): `src/server/services/incidentService.ts`
- [Findings and evidence](https://github.com/ngynduc/forenotes/blob/main/src/server/services/findingService.ts): `src/server/services/findingService.ts`
- [Tasks and notes](https://github.com/ngynduc/forenotes/blob/main/src/server/services/taskService.ts): `src/server/services/taskService.ts`
- [Timeline and indicators](https://github.com/ngynduc/forenotes/blob/main/src/server/services/timelineEventService.ts): `src/server/services/timelineEventService.ts`
- [Hunt queries](https://github.com/ngynduc/forenotes/blob/main/src/server/services/queryService.ts): `src/server/services/queryService.ts`

### Investigation and reporting

- [Dashboards](https://github.com/ngynduc/forenotes/blob/main/src/server/services/dashboardService.ts): `src/server/services/dashboardService.ts`
- [Search](https://github.com/ngynduc/forenotes/blob/main/src/server/services/searchService.ts): `src/server/services/searchService.ts`
- [Investigation graph](https://github.com/ngynduc/forenotes/blob/main/src/server/graph/graphBuilder.ts): `src/server/graph/graphBuilder.ts`
- [MITRE matrix](https://github.com/ngynduc/forenotes/blob/main/src/server/graph/mitreMatrixBuilder.ts): `src/server/graph/mitreMatrixBuilder.ts`
- [Report generation](https://github.com/ngynduc/forenotes/blob/main/src/server/services/reportService.ts): `src/server/services/reportService.ts`
- [PDF rendering](https://github.com/ngynduc/forenotes/blob/main/src/server/services/reportPdfRenderer.ts): `src/server/services/reportPdfRenderer.ts`

### State and integrations

- [Audit log](https://github.com/ngynduc/forenotes/blob/main/src/server/services/auditLogService.ts): `src/server/services/auditLogService.ts`
- [Notifications](https://github.com/ngynduc/forenotes/blob/main/src/server/services/notificationService.ts): `src/server/services/notificationService.ts`
- [PostgreSQL](https://github.com/ngynduc/forenotes/blob/main/src/server/db/pool.ts): `src/server/db/pool.ts`
- [Request transactions](https://github.com/ngynduc/forenotes/blob/main/src/server/db/transaction.ts): `src/server/db/transaction.ts`
- [Shared domain types](https://github.com/ngynduc/forenotes/blob/main/src/shared/domain.ts): `src/shared/domain.ts`
- [Report contracts](https://github.com/ngynduc/forenotes/blob/main/src/shared/reportTypes.ts): `src/shared/reportTypes.ts`
- [Report LLM client](https://github.com/ngynduc/forenotes/blob/main/src/server/services/litellmServiceClient.ts): `src/server/services/litellmServiceClient.ts`
- [MCP HTTP interface](https://github.com/ngynduc/forenotes/blob/main/src/server/mcp/mcpHttpHandler.ts): `src/server/mcp/mcpHttpHandler.ts`
- [MCP tools](https://github.com/ngynduc/forenotes/blob/main/src/server/mcp/registerMcpTools.ts): `src/server/mcp/registerMcpTools.ts`

### Other components

- **Responder**
- [Report LLM service](https://github.com/ngynduc/forenotes/blob/main/services/report-llm-service/app.py): `services/report-llm-service/app.py`

## Connections

- Responder → Forenotes UI: uses (evidence: `README.md`)
- Forenotes UI → Workspaces: renders
- Workspaces → API client: requests
- HTTP application → API routes: mounts (evidence: `src/server/app.ts`)
- HTTP application → Request transactions: wraps writes (evidence: `src/server/app.ts`)
- HTTP application → MCP HTTP interface: routes MCP (evidence: `src/server/app.ts`)
- API routes → Authentication: authenticates
- API routes → Report generation: dispatches reports
- API routes → Hunt queries: dispatches queries
- Hunt queries → Authorization: checks access (evidence: `src/server/services/queryService.ts`)
- Hunt queries → Audit log: records changes (evidence: `src/server/services/queryService.ts`)
- API routes → Findings and evidence: dispatches findings
- API routes → Tasks and notes: dispatches tasks
- API routes → MITRE matrix: builds matrix
- API routes → Investigation graph: builds graph
- Report generation → Report LLM client: requests generation (evidence: `src/server/services/reportService.ts`)
- Report generation → PDF rendering: renders PDF (evidence: `src/server/services/reportService.ts`)
- Report LLM client → Report LLM service: posts report context (evidence: `src/server/services/litellmServiceClient.ts`)
- MCP HTTP interface → MCP tools: registers tools (evidence: `src/server/mcp/mcpHttpHandler.ts`)
- Report generation → Report contracts: uses contracts (evidence: `src/server/services/reportService.ts`)
- HTTP application → PostgreSQL: uses pool (evidence: `src/server/app.ts`)
- Authentication → Notifications: publishes state (evidence: `src/server/services/authService.ts`)
