# hyptofon/soma architecture

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

- Interactive diagram: https://gitdiagram.com/hyptofon/soma
- Repository: https://github.com/hyptofon/soma

## Overview

SOMA is a neuro-adaptive agile project-management platform. A user works in a workspace to manage work items and sessions through the .NET API; separately, the cognitive engine exposes telemetry WebSockets and computes fatigue-driven browser actions. The tree also shows identity, collaboration, billing, privacy, device-agent, and personalization capabilities. Sampled code supports the work-item/provider and work-session interactions, device-link reads, billing-event reconciliation, workspace authorization, and engine HTTP/WebSocket exposure. Wiring for unsampled feature handlers and the telemetry hub-to-fatigue path is not asserted.

Main entry points: [`apps/api-dotnet/src/Soma.WebApi/Program.cs`](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Program.cs) (Web API), [`apps/api-dotnet/src/Soma.WebApi/Controllers/WorkItemsController.cs`](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Controllers/WorkItemsController.cs) (Work-item API), [`apps/api-dotnet/src/Soma.Infrastructure/Persistence/WorkSessionService.cs`](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.Infrastructure/Persistence/WorkSessionService.cs) (Work sessions), [`apps/cognitive-engine/internal/httpserver/server.go`](https://github.com/hyptofon/soma/blob/main/apps/cognitive-engine/internal/httpserver/server.go) (Cognitive HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_webapi["Web API<br/>[Program.cs]"]
  node_authorization["Workspace authorization"]
  node_auth["Identity and sessions<br/>[Auth]"]
end

subgraph group_work["Agile work"]
  node_workitems["Work-item API"]
  node_provider["Native work provider"]
  node_backlog["Backlog and stories<br/>[Backlog]"]
  node_sprints["Sprint planning<br/>[Sprints]"]
  node_tasks["Task management<br/>[Tasks]"]
  node_sessions["Work sessions"]
end

subgraph group_collab["Workspace services"]
  node_teams["Teams and membership<br/>[Teams]"]
  node_workspace["Workspace lifecycle<br/>[Workspaces]"]
  node_invites["Invitations<br/>[Invites]"]
  node_billing["Billing and entitlements<br/>[Billing]"]
  node_privacy["Privacy and consent<br/>[Privacy]"]
  node_agents["Device agents<br/>[Agents]"]
end

subgraph group_personal["Personalization"]
  node_adaptation["Adaptation profiles<br/>[Adaptation]"]
  node_accessibility["Accessibility settings<br/>[Accessibility]"]
end

subgraph group_cognitive["Cognitive engine"]
  node_cognitivehttp["Cognitive HTTP server<br/>[server.go]"]
  node_telemetryws["Telemetry WebSocket<br/>[server.go]"]
  node_fatigue["Fatigue scoring<br/>[engine.go]"]
end

node_user(("User"))

node_user -->|"sends requests"| node_webapi
node_webapi -->|"dispatches HTTP"| node_workitems
node_webapi -->|"authorizes workspace"| node_authorization
node_workitems -->|"calls provider"| node_provider
node_workitems -->|"starts work sessions"| node_sessions
node_sessions -->|"checks work reference"| node_provider
node_user -->|"sends telemetry"| node_cognitivehttp
node_cognitivehttp -->|"serves WebSocket"| node_telemetryws
node_telemetryws -->|"returns telemetry actions"| node_user

click node_webapi "https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Program.cs"
click node_authorization "https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Security/WorkspaceAuthorizationHandler.cs"
click node_auth "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Auth"
click node_workitems "https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Controllers/WorkItemsController.cs"
click node_provider "https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.Application/Common/Providers/SomaNativeProvider.cs"
click node_backlog "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Backlog"
click node_sprints "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Sprints"
click node_tasks "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Tasks"
click node_teams "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Teams"
click node_workspace "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Workspaces"
click node_invites "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Invites"
click node_billing "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Billing"
click node_privacy "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Privacy"
click node_agents "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Agents"
click node_sessions "https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.Infrastructure/Persistence/WorkSessionService.cs"
click node_adaptation "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Adaptation"
click node_accessibility "https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Accessibility"
click node_cognitivehttp "https://github.com/hyptofon/soma/blob/main/apps/cognitive-engine/internal/httpserver/server.go"
click node_telemetryws "https://github.com/hyptofon/soma/blob/main/apps/cognitive-engine/internal/httpserver/server.go"
click node_fatigue "https://github.com/hyptofon/soma/blob/main/apps/cognitive-engine/internal/fatigue/engine.go"

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_webapi,node_authorization,node_auth,node_user toneBlue
class node_workitems,node_provider,node_backlog,node_sprints,node_tasks,node_sessions toneAmber
class node_teams,node_workspace,node_invites,node_billing,node_privacy,node_agents toneMint
class node_adaptation,node_accessibility toneRose
class node_cognitivehttp,node_telemetryws,node_fatigue toneIndigo
```

## Components

### API and access

- [Web API](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Program.cs): `apps/api-dotnet/src/Soma.WebApi/Program.cs`
- [Workspace authorization](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Security/WorkspaceAuthorizationHandler.cs): `apps/api-dotnet/src/Soma.WebApi/Security/WorkspaceAuthorizationHandler.cs`
- [Identity and sessions](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Auth): `apps/api-dotnet/src/Soma.Application/Features/Auth`

### Agile work

- [Work-item API](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.WebApi/Controllers/WorkItemsController.cs): `apps/api-dotnet/src/Soma.WebApi/Controllers/WorkItemsController.cs`
- [Native work provider](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.Application/Common/Providers/SomaNativeProvider.cs): `apps/api-dotnet/src/Soma.Application/Common/Providers/SomaNativeProvider.cs`
- [Backlog and stories](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Backlog): `apps/api-dotnet/src/Soma.Application/Features/Backlog`
- [Sprint planning](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Sprints): `apps/api-dotnet/src/Soma.Application/Features/Sprints`
- [Task management](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Tasks): `apps/api-dotnet/src/Soma.Application/Features/Tasks`
- [Work sessions](https://github.com/hyptofon/soma/blob/main/apps/api-dotnet/src/Soma.Infrastructure/Persistence/WorkSessionService.cs): `apps/api-dotnet/src/Soma.Infrastructure/Persistence/WorkSessionService.cs`

### Workspace services

- [Teams and membership](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Teams): `apps/api-dotnet/src/Soma.Application/Features/Teams`
- [Workspace lifecycle](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Workspaces): `apps/api-dotnet/src/Soma.Application/Features/Workspaces`
- [Invitations](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Invites): `apps/api-dotnet/src/Soma.Application/Features/Invites`
- [Billing and entitlements](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Billing): `apps/api-dotnet/src/Soma.Application/Features/Billing`
- [Privacy and consent](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Privacy): `apps/api-dotnet/src/Soma.Application/Features/Privacy`
- [Device agents](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Agents): `apps/api-dotnet/src/Soma.Application/Features/Agents`

### Personalization

- [Adaptation profiles](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Adaptation): `apps/api-dotnet/src/Soma.Application/Features/Adaptation`
- [Accessibility settings](https://github.com/hyptofon/soma/tree/main/apps/api-dotnet/src/Soma.Application/Features/Accessibility): `apps/api-dotnet/src/Soma.Application/Features/Accessibility`

### Cognitive engine

- [Cognitive HTTP server](https://github.com/hyptofon/soma/blob/main/apps/cognitive-engine/internal/httpserver/server.go): `apps/cognitive-engine/internal/httpserver/server.go`
- [Telemetry WebSocket](https://github.com/hyptofon/soma/blob/main/apps/cognitive-engine/internal/httpserver/server.go): `apps/cognitive-engine/internal/httpserver/server.go`
- [Fatigue scoring](https://github.com/hyptofon/soma/blob/main/apps/cognitive-engine/internal/fatigue/engine.go): `apps/cognitive-engine/internal/fatigue/engine.go`

### Other components

- **User**

## Connections

- User → Web API: sends requests
- Web API → Work-item API: dispatches HTTP
- Web API → Workspace authorization: authorizes workspace
- Work-item API → Native work provider: calls provider
- Work-item API → Work sessions: starts work sessions
- Work sessions → Native work provider: checks work reference
- User → Cognitive HTTP server: sends telemetry
- Cognitive HTTP server → Telemetry WebSocket: serves WebSocket
- Telemetry WebSocket → User: returns telemetry actions