# pranjalchirmade09326-hash/mindspace architecture

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

- Interactive diagram: https://gitdiagram.com/pranjalchirmade09326-hash/mindspace
- Repository: https://github.com/pranjalchirmade09326-hash/mindspace

## Overview

MindSpace is a mental-wellbeing and peer-support platform with five role workspaces. A member uses wellbeing tools or a voice companion; deterministic crisis screening precedes AI processing, and AI operations go through authenticated REST APIs rather than direct database access. The platform also supports peer matching, listener supervision, safety operations, and clinical-record services. The graph reflects README-documented capabilities and the sampled entry points; many routes and service internals were not sampled, so uncertain connections are omitted or dashed.

Main entry points: [`frontend`](https://github.com/pranjalchirmade09326-hash/mindspace/tree/main/frontend) (Role Workspaces), [`agents/src/orchestrator.py`](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/orchestrator.py) (Agent Orchestrator), [`backend/mindspace-fastapi/app/main.py`](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/main.py) (Core Health API), [`agents/src/main.py`](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/main.py) (Agent Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and Identity"]
  node_role_workspaces["Role Workspaces"]
  node_workflow_api["Workflow API"]
  node_auth["Identity Service<br/>[main.py]"]
end

subgraph group_agents["Wellbeing Agents"]
  node_agent_entry["Agent Service<br/>[main.py]"]
  node_agent_graph["Agent Orchestrator<br/>[orchestrator.py]"]
  node_crisis_sentinel["Crisis Sentinel<br/>[safety_sentinel.py]"]
  node_intake["Wellbeing Intake<br/>[intake_agent.py]"]
  node_companion["AI Companion<br/>[companion_agent.py]"]
  node_llm["LLM Gateway<br/>[llm_client.py]"]
  node_voice["Voice Service<br/>[voice_service.py]"]
end

subgraph group_core["MindSpace Core"]
  node_mindspace_api["Core Health API<br/>[main.py]"]
  node_peer_ops["Peer and Safety Operations"]
  node_ws_manager["Conversation WebSockets"]
end

subgraph group_fhir["FHIR Services"]
  node_fhir_gql["FHIR GraphQL and REST<br/>[main.py]"]
  node_fhir_routes["FHIR Resource Routes"]
  node_fhir_server["FHIR Server<br/>[main.py]"]
  node_fhir_staging["Record Staging<br/>[main.py]"]
  node_fhir_mcp["FHIR MCP Service<br/>[main.py]"]
end

subgraph group_data["Persistence and Integrations"]
  node_health_db[("Health PostgreSQL<br/>[database.py]")]
  node_fhir_db[("FHIR PostgreSQL<br/>[database.py]")]
  node_frontend_db[("Frontend PostgreSQL<br/>[db.ts]")]
end

node_member(("Member"))
node_peer_listener(("Peer Listener"))

node_member -->|"uses"| node_role_workspaces
node_role_workspaces -.->|"submits workflows"| node_workflow_api
node_role_workspaces -.->|"authenticates"| node_auth
node_role_workspaces -.->|"requests wellbeing support"| node_agent_entry
node_agent_entry -->|"dispatches"| node_agent_graph
node_agent_graph -->|"screens first"| node_crisis_sentinel
node_agent_graph -.->|"dispatches intake"| node_intake
node_agent_graph -.->|"dispatches support"| node_companion
node_companion -.->|"requests completion"| node_llm
node_agent_entry -->|"serves voice"| node_voice
node_voice -->|"streams speech"| node_member
node_role_workspaces -.->|"calls REST API"| node_mindspace_api
node_mindspace_api -.->|"exposes operations"| node_peer_ops
node_mindspace_api -->|"initializes database"| node_health_db
node_peer_listener -->|"uses listener workspace"| node_role_workspaces
node_peer_ops -.->|"reads and writes"| node_health_db
node_mindspace_api -.->|"supports live conversations"| node_ws_manager
node_fhir_gql -->|"mounts routes"| node_fhir_routes
node_fhir_gql -.->|"uses FHIR services"| node_fhir_server
node_fhir_server -->|"connects database"| node_fhir_db
node_fhir_staging -.->|"stores staged records"| node_fhir_db
node_fhir_mcp -.->|"connects to FHIR"| node_fhir_server
node_role_workspaces -.->|"uses application data"| node_frontend_db

click node_role_workspaces "https://github.com/pranjalchirmade09326-hash/mindspace/tree/main/frontend"
click node_workflow_api "https://github.com/pranjalchirmade09326-hash/mindspace/tree/main/frontend/src/app/api/workflow"
click node_auth "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-iam-py/app/main.py"
click node_agent_entry "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/main.py"
click node_agent_graph "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/orchestrator.py"
click node_crisis_sentinel "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/safety_sentinel.py"
click node_intake "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/intake_agent.py"
click node_companion "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/companion_agent.py"
click node_llm "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/llm_client.py"
click node_voice "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/voice_service.py"
click node_mindspace_api "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/main.py"
click node_peer_ops "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/services/operations_service.py"
click node_ws_manager "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/core/websocket_manager.py"
click node_fhir_gql "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-gql/app/main.py"
click node_fhir_routes "https://github.com/pranjalchirmade09326-hash/mindspace/tree/main/backend/fhir-gql/app/routers"
click node_fhir_server "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-server/app/main.py"
click node_fhir_staging "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-staging/app/main.py"
click node_fhir_mcp "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-mcp/app/main.py"
click node_health_db "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/core/database.py"
click node_fhir_db "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-server/app/core/database.py"
click node_frontend_db "https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/frontend/prisma/db.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_role_workspaces,node_workflow_api,node_auth toneBlue
class node_agent_entry,node_agent_graph,node_crisis_sentinel,node_intake,node_companion,node_llm,node_voice toneAmber
class node_mindspace_api,node_peer_ops,node_ws_manager toneMint
class node_fhir_gql,node_fhir_routes,node_fhir_server,node_fhir_staging,node_fhir_mcp toneRose
class node_health_db,node_fhir_db,node_frontend_db,node_member,node_peer_listener toneIndigo
```

## Components

### Web and Identity

- [Role Workspaces](https://github.com/pranjalchirmade09326-hash/mindspace/tree/main/frontend): `frontend`
- [Workflow API](https://github.com/pranjalchirmade09326-hash/mindspace/tree/main/frontend/src/app/api/workflow): `frontend/src/app/api/workflow`
- [Identity Service](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-iam-py/app/main.py): `backend/mindspace-iam-py/app/main.py`

### Wellbeing Agents

- [Agent Service](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/main.py): `agents/src/main.py`
- [Agent Orchestrator](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/orchestrator.py): `agents/src/orchestrator.py`
- [Crisis Sentinel](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/safety_sentinel.py): `agents/src/nodes/safety_sentinel.py`
- [Wellbeing Intake](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/intake_agent.py): `agents/src/nodes/intake_agent.py`
- [AI Companion](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/companion_agent.py): `agents/src/nodes/companion_agent.py`
- [LLM Gateway](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/llm_client.py): `agents/src/nodes/llm_client.py`
- [Voice Service](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/agents/src/nodes/voice_service.py): `agents/src/nodes/voice_service.py`

### MindSpace Core

- [Core Health API](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/main.py): `backend/mindspace-fastapi/app/main.py`
- [Peer and Safety Operations](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/services/operations_service.py): `backend/mindspace-fastapi/app/services/operations_service.py`
- [Conversation WebSockets](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/core/websocket_manager.py): `backend/mindspace-fastapi/app/core/websocket_manager.py`

### FHIR Services

- [FHIR GraphQL and REST](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-gql/app/main.py): `backend/fhir-gql/app/main.py`
- [FHIR Resource Routes](https://github.com/pranjalchirmade09326-hash/mindspace/tree/main/backend/fhir-gql/app/routers): `backend/fhir-gql/app/routers`
- [FHIR Server](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-server/app/main.py): `backend/fhir-server/app/main.py`
- [Record Staging](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-staging/app/main.py): `backend/fhir-staging/app/main.py`
- [FHIR MCP Service](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-mcp/app/main.py): `backend/fhir-mcp/app/main.py`

### Persistence and Integrations

- [Health PostgreSQL](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/mindspace-fastapi/app/core/database.py): `backend/mindspace-fastapi/app/core/database.py`
- [FHIR PostgreSQL](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/backend/fhir-server/app/core/database.py): `backend/fhir-server/app/core/database.py`
- [Frontend PostgreSQL](https://github.com/pranjalchirmade09326-hash/mindspace/blob/main/frontend/prisma/db.ts): `frontend/prisma/db.ts`

### Other components

- **Member**
- **Peer Listener**

## Connections

- Member → Role Workspaces: uses
- Role Workspaces → Workflow API: submits workflows (evidence: `frontend/src/app/api/workflow/route.ts`)
- Role Workspaces → Identity Service: authenticates
- Role Workspaces → Agent Service: requests wellbeing support
- Agent Service → Agent Orchestrator: dispatches (evidence: `agents/src/main.py`)
- Agent Orchestrator → Crisis Sentinel: screens first
- Agent Orchestrator → Wellbeing Intake: dispatches intake
- Agent Orchestrator → AI Companion: dispatches support
- AI Companion → LLM Gateway: requests completion
- Agent Service → Voice Service: serves voice (evidence: `agents/src/main.py`)
- Voice Service → Member: streams speech
- Role Workspaces → Core Health API: calls REST API
- Core Health API → Peer and Safety Operations: exposes operations
- Core Health API → Health PostgreSQL: initializes database (evidence: `backend/mindspace-fastapi/app/main.py`)
- Peer Listener → Role Workspaces: uses listener workspace
- Peer and Safety Operations → Health PostgreSQL: reads and writes
- Core Health API → Conversation WebSockets: supports live conversations
- FHIR GraphQL and REST → FHIR Resource Routes: mounts routes (evidence: `backend/fhir-gql/app/main.py`)
- FHIR GraphQL and REST → FHIR Server: uses FHIR services
- FHIR Server → FHIR PostgreSQL: connects database (evidence: `backend/fhir-server/app/main.py`)
- Record Staging → FHIR PostgreSQL: stores staged records (evidence: `backend/fhir-staging/app/main.py`)
- FHIR MCP Service → FHIR Server: connects to FHIR
- Role Workspaces → Frontend PostgreSQL: uses application data
