# pman369/stateos architecture

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

- Interactive diagram: https://gitdiagram.com/pman369/stateos
- Repository: https://github.com/pman369/stateos

## Overview

StateOS is a React Native human-capability app centered on a short path from launch or recommendation to a guided somatic protocol, session execution, and reflection. Its broader documented capabilities include capability-state views, insights, journaling, identity/profile, settings, and a guarded AI coach. The graph shows sampled navigation, protocol, session, and coach relationships; other screens are preserved as navigation destinations. The README describes telemetry, privacy, and product behavior, but the sampled source does not establish their runtime data flows or external integrations.

Main entry points: [`src/navigation/RootNavigator.tsx`](https://github.com/pman369/stateos/blob/main/src/navigation/RootNavigator.tsx) (Root Navigation), [`src/screens/AICoachScreen.tsx`](https://github.com/pman369/stateos/blob/main/src/screens/AICoachScreen.tsx) (AI Coach), [`src/screens/ProtocolPlayerScreen.tsx`](https://github.com/pman369/stateos/blob/main/src/screens/ProtocolPlayerScreen.tsx) (Protocol Player), [`src/screens/ProtocolsScreen.tsx`](https://github.com/pman369/stateos/blob/main/src/screens/ProtocolsScreen.tsx) (Protocol Library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_app_entry["App Entry<br/>[App.tsx]"]
  node_navigation["Root Navigation<br/>[RootNavigator.tsx]"]
end

subgraph group_experience["User Experiences"]
  node_home["Home<br/>[HomeScreen.tsx]"]
  node_state["Capability State<br/>[StateScreen.tsx]"]
  node_journal["Journal<br/>[JournalScreen.tsx]"]
  node_insights["Insights<br/>[InsightsScreen.tsx]"]
  node_profile["Profile<br/>[ProfileScreen.tsx]"]
  node_settings["Settings<br/>[SettingsScreen.tsx]"]
  node_coach_screen["AI Coach<br/>[AICoachScreen.tsx]"]
end

subgraph group_protocols["Protocol Execution"]
  node_protocol_catalog["Protocol Library"]
  node_protocol_data["Protocol Definitions<br/>[protocols.ts]"]
  node_player["Protocol Player"]
  node_session_store["Session FSM<br/>[sessionStore.ts]"]
end

subgraph group_foundation["Domain and Data"]
  node_capability_data["Capability Domains<br/>[capabilities.ts]"]
  node_ai_service["Coach Guardrails<br/>[aiCoach.ts]"]
  node_schemas["Validation Schemas<br/>[index.ts]"]
  node_types["Domain Types<br/>[index.ts]"]
  node_db_client["SQLite Client<br/>[client.ts]"]
  node_db_schema[("Local Database Schema<br/>[schema.ts]")]
  node_design_tokens["Design Tokens<br/>[tokens.ts]"]
end

node_user(("User"))

node_user -->|"opens"| node_app_entry
node_app_entry -->|"renders"| node_navigation
node_navigation -->|"routes to"| node_home
node_navigation -->|"routes to"| node_state
node_navigation -->|"routes to"| node_protocol_catalog
node_navigation -->|"routes to"| node_journal
node_navigation -->|"routes to"| node_insights
node_navigation -->|"routes to"| node_coach_screen
node_navigation -->|"routes to"| node_profile
node_navigation -->|"routes to"| node_settings
node_navigation -->|"registers modal"| node_player
node_protocol_catalog -->|"lists protocols"| node_protocol_data
node_protocol_catalog -->|"launches protocol"| node_player
node_player -->|"updates session"| node_session_store
node_state -->|"reads domains"| node_capability_data
node_coach_screen -->|"requests response"| node_ai_service
node_ai_service -->|"validates response"| node_schemas
node_coach_screen -->|"resolves recommendation"| node_protocol_data
node_coach_screen -->|"launches recommendation"| node_player
node_session_store -->|"uses transitions"| node_types
node_schemas -->|"checks transition rules"| node_types
node_db_client -->|"initializes database"| node_db_schema

click node_app_entry "https://github.com/pman369/stateos/blob/main/App.tsx"
click node_navigation "https://github.com/pman369/stateos/blob/main/src/navigation/RootNavigator.tsx"
click node_home "https://github.com/pman369/stateos/blob/main/src/screens/HomeScreen.tsx"
click node_state "https://github.com/pman369/stateos/blob/main/src/screens/StateScreen.tsx"
click node_journal "https://github.com/pman369/stateos/blob/main/src/screens/JournalScreen.tsx"
click node_insights "https://github.com/pman369/stateos/blob/main/src/screens/InsightsScreen.tsx"
click node_profile "https://github.com/pman369/stateos/blob/main/src/screens/ProfileScreen.tsx"
click node_settings "https://github.com/pman369/stateos/blob/main/src/screens/SettingsScreen.tsx"
click node_coach_screen "https://github.com/pman369/stateos/blob/main/src/screens/AICoachScreen.tsx"
click node_protocol_catalog "https://github.com/pman369/stateos/blob/main/src/screens/ProtocolsScreen.tsx"
click node_protocol_data "https://github.com/pman369/stateos/blob/main/src/data/protocols.ts"
click node_player "https://github.com/pman369/stateos/blob/main/src/screens/ProtocolPlayerScreen.tsx"
click node_session_store "https://github.com/pman369/stateos/blob/main/src/store/sessionStore.ts"
click node_capability_data "https://github.com/pman369/stateos/blob/main/src/data/capabilities.ts"
click node_ai_service "https://github.com/pman369/stateos/blob/main/src/services/aiCoach.ts"
click node_schemas "https://github.com/pman369/stateos/blob/main/src/schemas/index.ts"
click node_types "https://github.com/pman369/stateos/blob/main/src/types/index.ts"
click node_db_client "https://github.com/pman369/stateos/blob/main/src/db/client.ts"
click node_db_schema "https://github.com/pman369/stateos/blob/main/src/db/schema.ts"
click node_design_tokens "https://github.com/pman369/stateos/blob/main/src/constants/tokens.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_app_entry,node_navigation,node_user toneBlue
class node_home,node_state,node_journal,node_insights,node_profile,node_settings,node_coach_screen toneAmber
class node_protocol_catalog,node_protocol_data,node_player,node_session_store toneMint
class node_capability_data,node_ai_service,node_schemas,node_types,node_db_client,node_db_schema,node_design_tokens toneRose
```

## Components

### App Shell

- [App Entry](https://github.com/pman369/stateos/blob/main/App.tsx): `App.tsx`
- [Root Navigation](https://github.com/pman369/stateos/blob/main/src/navigation/RootNavigator.tsx): `src/navigation/RootNavigator.tsx`

### User Experiences

- [Home](https://github.com/pman369/stateos/blob/main/src/screens/HomeScreen.tsx): `src/screens/HomeScreen.tsx`
- [Capability State](https://github.com/pman369/stateos/blob/main/src/screens/StateScreen.tsx): `src/screens/StateScreen.tsx`
- [Journal](https://github.com/pman369/stateos/blob/main/src/screens/JournalScreen.tsx): `src/screens/JournalScreen.tsx`
- [Insights](https://github.com/pman369/stateos/blob/main/src/screens/InsightsScreen.tsx): `src/screens/InsightsScreen.tsx`
- [Profile](https://github.com/pman369/stateos/blob/main/src/screens/ProfileScreen.tsx): `src/screens/ProfileScreen.tsx`
- [Settings](https://github.com/pman369/stateos/blob/main/src/screens/SettingsScreen.tsx): `src/screens/SettingsScreen.tsx`
- [AI Coach](https://github.com/pman369/stateos/blob/main/src/screens/AICoachScreen.tsx): `src/screens/AICoachScreen.tsx`

### Protocol Execution

- [Protocol Library](https://github.com/pman369/stateos/blob/main/src/screens/ProtocolsScreen.tsx): `src/screens/ProtocolsScreen.tsx`
- [Protocol Definitions](https://github.com/pman369/stateos/blob/main/src/data/protocols.ts): `src/data/protocols.ts`
- [Protocol Player](https://github.com/pman369/stateos/blob/main/src/screens/ProtocolPlayerScreen.tsx): `src/screens/ProtocolPlayerScreen.tsx`
- [Session FSM](https://github.com/pman369/stateos/blob/main/src/store/sessionStore.ts): `src/store/sessionStore.ts`

### Domain and Data

- [Capability Domains](https://github.com/pman369/stateos/blob/main/src/data/capabilities.ts): `src/data/capabilities.ts`
- [Coach Guardrails](https://github.com/pman369/stateos/blob/main/src/services/aiCoach.ts): `src/services/aiCoach.ts`
- [Validation Schemas](https://github.com/pman369/stateos/blob/main/src/schemas/index.ts): `src/schemas/index.ts`
- [Domain Types](https://github.com/pman369/stateos/blob/main/src/types/index.ts): `src/types/index.ts`
- [SQLite Client](https://github.com/pman369/stateos/blob/main/src/db/client.ts): `src/db/client.ts`
- [Local Database Schema](https://github.com/pman369/stateos/blob/main/src/db/schema.ts): `src/db/schema.ts`
- [Design Tokens](https://github.com/pman369/stateos/blob/main/src/constants/tokens.ts): `src/constants/tokens.ts`

### Other components

- **User**

## Connections

- User → App Entry: opens (evidence: `README.md`)
- App Entry → Root Navigation: renders (evidence: `App.tsx`)
- Root Navigation → Home: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → Capability State: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → Protocol Library: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → Journal: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → Insights: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → AI Coach: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → Profile: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → Settings: routes to (evidence: `src/navigation/RootNavigator.tsx`)
- Root Navigation → Protocol Player: registers modal (evidence: `src/navigation/RootNavigator.tsx`)
- Protocol Library → Protocol Definitions: lists protocols (evidence: `src/screens/ProtocolsScreen.tsx`)
- Protocol Library → Protocol Player: launches protocol (evidence: `README.md`)
- Protocol Player → Session FSM: updates session (evidence: `src/screens/ProtocolPlayerScreen.tsx`)
- Capability State → Capability Domains: reads domains (evidence: `src/screens/StateScreen.tsx`)
- AI Coach → Coach Guardrails: requests response (evidence: `src/screens/AICoachScreen.tsx`)
- Coach Guardrails → Validation Schemas: validates response (evidence: `src/services/aiCoach.ts`)
- AI Coach → Protocol Definitions: resolves recommendation (evidence: `src/screens/AICoachScreen.tsx`)
- AI Coach → Protocol Player: launches recommendation (evidence: `src/screens/AICoachScreen.tsx`)
- Session FSM → Domain Types: uses transitions (evidence: `src/store/sessionStore.ts`)
- Validation Schemas → Domain Types: checks transition rules (evidence: `src/schemas/index.ts`)
- SQLite Client → Local Database Schema: initializes database (evidence: `src/db/client.ts`)