# audioreach/audioreach-creator-backend architecture

> Architecture diagram of the GitHub repository audioreach/audioreach-creator-backend, 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/audioreach/audioreach-creator-backend
- Repository: https://github.com/audioreach/audioreach-creator-backend

## Overview

AudioReach Creator API is a NestJS backend for managing .awsp/.acdb files and audio-graph data. The principal read workflow is client REST request → CQRS query dispatch → application handler → persistence query service → SQLite-backed adapter, with the handler mapping read models for the API response. The tree and excerpts support the query path and persistence wiring; the README documents file upload/parsing and broader architecture, but their exact runtime calls are not shown. Planned capabilities are marked as unverified.

Main entry points: [`packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts`](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts) (Query dispatch), [`packages/infrastructure/persistence/src/persistence-typeorm-sqllite/entity-schema/entity-table-names.ts`](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/entity-schema/entity-table-names.ts) (SQLite entities), [`packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts`](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts) (Query service wiring), [`packages/api/src/main.ts`](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/api/src/main.ts) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["REST presentation"]
  node_rest["REST API<br/>[main.ts]"]
  node_graph_api["Graph operations"]
  node_auth_api["Authentication"]
  node_api_result["API result DTO<br/>[api-result.dto.ts]"]
end

subgraph group_application["CQRS application"]
  node_query_registry["Query dispatch"]
  node_container_handler["Container queries"]
  node_module_handler["Module queries"]
  node_query_ports["Query service ports<br/>[query-services.ts]"]
  node_result_model["Result envelope<br/>[result.ts]"]
end

subgraph group_persistence["Persistence adapters"]
  node_typeorm_factory["Query service wiring"]
  node_bulk_read["Bulk graph reads"]
  node_definition_reads["Definition reads"]
  node_module_reads["Module reads"]
  node_edit_sessions["Edit session data"]
  node_sqlite[("SQLite entities")]
end

subgraph group_capabilities["Product capabilities"]
  node_file_workflow["File upload and parsing"]
  node_download["File download"]
  node_diff_merge["ACDB diff merge"]
  node_device_tuning["Device tuning"]
  node_simulation["Usecase simulation"]
  node_plugins["Custom modules"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_rest
node_rest -->|"exposes endpoints"| node_graph_api
node_rest -.->|"exposes endpoints"| node_auth_api
node_graph_api -.->|"requests queries"| node_query_registry
node_query_registry -->|"dispatches"| node_container_handler
node_query_registry -->|"dispatches"| node_module_handler
node_container_handler -->|"calls query services"| node_query_ports
node_module_handler -->|"calls query services"| node_query_ports
node_query_registry -->|"types dependencies"| node_query_ports
node_typeorm_factory -->|"constructs services"| node_bulk_read
node_typeorm_factory -->|"constructs services"| node_definition_reads
node_typeorm_factory -->|"constructs services"| node_module_reads
node_bulk_read -->|"reads entities"| node_sqlite
node_definition_reads -->|"loads edit actions"| node_edit_sessions
node_module_reads -.->|"queries entities"| node_sqlite
node_file_workflow -->|"stores parsed data"| node_sqlite
node_download -.->|"reads file data"| node_sqlite
node_container_handler -->|"returns result"| node_result_model
node_result_model -.->|"maps response"| node_api_result
node_client -.->|"planned workflow"| node_diff_merge
node_client -.->|"planned workflow"| node_device_tuning
node_client -.->|"planned workflow"| node_simulation
node_client -.->|"planned extension"| node_plugins

click node_rest "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/api/src/main.ts"
click node_graph_api "https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/api/src/presentation/rest/modules"
click node_auth_api "https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/api/src/presentation/rest/modules/authentication"
click node_query_registry "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts"
click node_container_handler "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/usecase-designer/container/query/query-containers.handler.ts"
click node_module_handler "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/usecase-designer/spf-module/query/query-spf-modules.handler.ts"
click node_query_ports "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/ports/persistence/query-services/query-services.ts"
click node_result_model "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/shared/result/result.ts"
click node_api_result "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/api/src/presentation/rest/common/dto/api-response/api-result.dto.ts"
click node_typeorm_factory "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts"
click node_bulk_read "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/bulk-read/typeorm-bulk-read-query-service.ts"
click node_definition_reads "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/spf-module-definition/db-spf-module-definition-query-service.ts"
click node_module_reads "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/spf-module/db-spf-module-query-service.ts"
click node_edit_sessions "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/edit-session/edit-actions-query-service.ts"
click node_sqlite "https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/entity-schema/entity-table-names.ts"
click node_file_workflow "https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/core/src/application/file-operations"
click node_download "https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/core/src/application/file-operations/download-file"

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_rest,node_graph_api,node_auth_api,node_api_result,node_client toneBlue
class node_query_registry,node_container_handler,node_module_handler,node_query_ports,node_result_model toneAmber
class node_typeorm_factory,node_bulk_read,node_definition_reads,node_module_reads,node_edit_sessions,node_sqlite toneMint
class node_file_workflow,node_download,node_diff_merge,node_device_tuning,node_simulation,node_plugins toneRose
```

## Components

### REST presentation

- [REST API](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/api/src/main.ts): `packages/api/src/main.ts`
- [Graph operations](https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/api/src/presentation/rest/modules): `packages/api/src/presentation/rest/modules`
- [Authentication](https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/api/src/presentation/rest/modules/authentication): `packages/api/src/presentation/rest/modules/authentication`
- [API result DTO](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/api/src/presentation/rest/common/dto/api-response/api-result.dto.ts): `packages/api/src/presentation/rest/common/dto/api-response/api-result.dto.ts`

### CQRS application

- [Query dispatch](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts): `packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts`
- [Container queries](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/usecase-designer/container/query/query-containers.handler.ts): `packages/core/src/application/usecase-designer/container/query/query-containers.handler.ts`
- [Module queries](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/usecase-designer/spf-module/query/query-spf-modules.handler.ts): `packages/core/src/application/usecase-designer/spf-module/query/query-spf-modules.handler.ts`
- [Query service ports](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/ports/persistence/query-services/query-services.ts): `packages/core/src/application/ports/persistence/query-services/query-services.ts`
- [Result envelope](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/core/src/application/shared/result/result.ts): `packages/core/src/application/shared/result/result.ts`

### Persistence adapters

- [Query service wiring](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts): `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts`
- [Bulk graph reads](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/bulk-read/typeorm-bulk-read-query-service.ts): `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/bulk-read/typeorm-bulk-read-query-service.ts`
- [Definition reads](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/spf-module-definition/db-spf-module-definition-query-service.ts): `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/spf-module-definition/db-spf-module-definition-query-service.ts`
- [Module reads](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/spf-module/db-spf-module-query-service.ts): `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/spf-module/db-spf-module-query-service.ts`
- [Edit session data](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/edit-session/edit-actions-query-service.ts): `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/edit-session/edit-actions-query-service.ts`
- [SQLite entities](https://github.com/audioreach/audioreach-creator-backend/blob/feature/use-case-designer/packages/infrastructure/persistence/src/persistence-typeorm-sqllite/entity-schema/entity-table-names.ts): `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/entity-schema/entity-table-names.ts`

### Product capabilities

- [File upload and parsing](https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/core/src/application/file-operations): `packages/core/src/application/file-operations`
- [File download](https://github.com/audioreach/audioreach-creator-backend/tree/feature/use-case-designer/packages/core/src/application/file-operations/download-file): `packages/core/src/application/file-operations/download-file`
- **ACDB diff merge**
- **Device tuning**
- **Usecase simulation**
- **Custom modules**

### Other components

- **API client**

## Connections

- API client → REST API: sends requests (evidence: `README.md`)
- REST API → Graph operations: exposes endpoints (evidence: `README.md`)
- REST API → Authentication: exposes endpoints
- Graph operations → Query dispatch: requests queries
- Query dispatch → Container queries: dispatches (evidence: `packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts`)
- Query dispatch → Module queries: dispatches (evidence: `packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts`)
- Container queries → Query service ports: calls query services (evidence: `packages/core/src/application/usecase-designer/container/query/query-containers.handler.ts`)
- Module queries → Query service ports: calls query services (evidence: `packages/core/src/application/usecase-designer/spf-module/query/query-spf-modules.handler.ts`)
- Query dispatch → Query service ports: types dependencies (evidence: `packages/core/src/application/orchestration/cqrs/registries/query-handler-registry.ts`)
- Query service wiring → Bulk graph reads: constructs services (evidence: `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts`)
- Query service wiring → Definition reads: constructs services (evidence: `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts`)
- Query service wiring → Module reads: constructs services (evidence: `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/typeorm-query-services.ts`)
- Bulk graph reads → SQLite entities: reads entities (evidence: `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/bulk-read/typeorm-bulk-read-query-service.ts`)
- Definition reads → Edit session data: loads edit actions (evidence: `packages/infrastructure/persistence/src/persistence-typeorm-sqllite/queries/spf-module-definition/db-spf-module-definition-query-service.ts`)
- Module reads → SQLite entities: queries entities
- File upload and parsing → SQLite entities: stores parsed data (evidence: `README.md`)
- File download → SQLite entities: reads file data
- Container queries → Result envelope: returns result (evidence: `packages/core/src/application/usecase-designer/container/query/query-containers.handler.ts`)
- Result envelope → API result DTO: maps response
- API client → ACDB diff merge: planned workflow (evidence: `README.md`)
- API client → Device tuning: planned workflow (evidence: `README.md`)
- API client → Usecase simulation: planned workflow (evidence: `README.md`)
- API client → Custom modules: planned extension (evidence: `README.md`)