# aakash-kr-7/sol architecture

> Architecture diagram of the GitHub repository aakash-kr-7/sol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aakash-kr-7/sol
- Repository: https://github.com/aakash-kr-7/sol

## Overview

1. **Top-level architecture**
   - This repo is a two-part MVP: a **Flutter client** in `frontend/companion_app` and a **FastAPI backend** in `backend`.
   - The product is centered on a persistent AI companion with long-lived memory, relationship state, proactive outreach, and privacy controls.

2. **Client boundary**
   - The Flutter app is the presentation and session layer for auth, onboarding, chat, inbox, memory vault, profile/privacy, settings, and companion-specific UX.
   - Platform support is broad: Android, iOS, web, macOS, Windows, and Linux are all scaffolded, but the app logic lives primarily in `lib/`.
   - The client talks to the backend through `lib/services/api_service.dart` and related services, not directly to any data store.

3. **Authentication and session bootstrap**
   - Authentication is Firebase-backed on the client and server-verified in the backend.
   - `backend/auth/firebase.py` handles token verification, while the Flutter side uses `auth_service.dart`, `session_bootstrap_service.dart`, and `biometric_service.dart` to establish user/session state.
   - This creates a hard boundary between device identity, Firebase identity, and the backend’s pair-scoped application identity.

4. **Backend API surface**
   - The backend is organized as route modules under `backend/api`: `chat`, `profile`, `onboarding`, `notifications`, `proactive`, and `ops`.
   - These are the main external entry points and map cleanly to product concerns: conversation, user state, first-run setup, notification delivery, proactive messaging, and admin visibility.
   - `backend/main.py` is the API composition root that wires these routes into the FastAPI app.

5. **Conversation orchestration**
   - Chat is not just message forwarding; it is orchestrated through `backend/core/chat`-style responsibilities spread across `context_builder.py`, `llm.py`, `summarizer.py`, `burst_engine.py`, and `concurrency.py`.
   - The architecture suggests the backend prepares rich context, calls an LLM, then returns response content with pacing/burst metadata for the client to render as a believable companion interaction.
   - `frontend/companion_app/lib/services/burst_playback_service.dart` and UI widgets like `typing_indicator.dart` and `message_bubble.dart` support that playback model.

6. **Memory system**
   - Persistent memory is a first-class subsystem under `backend/memory`, with separate components for extraction, analysis, consolidation, retrieval, storage, and relationship inference.
   - This likely forms the long-term continuity engine: short-term conversation signals are distilled into durable memory objects and relationship state.
   - The repo also includes `backend/db/schema.sql` and `backend/DATA_MODEL.md`, indicating the memory/relationship model is explicitly designed rather than incidental.

7. **Relationship and personalization layer**
   - `backend/personality` contains character definitions in JSON and a loader/registry, which means the app supports multiple companions rather than a single generic persona.
   - This layer is a content boundary: character identity, tone, and behavioral rules are data-driven and separated from core orchestration logic.
   - It aligns with the “multi-companion roster” described in the README and the character-focused screens in the Flutter app.

8. **Proactive behavior**
   - Proactive engagement is isolated in `backend/core/proactive_engine.py` and exposed through `backend/api/proactive.py` and `backend/api/notifications.py`.
   - Supporting files like `backend/core/life_simulator.py` and `backend/core/burst_engine.py` suggest the backend can simulate or schedule companion-driven outreach rather than waiting only for user-initiated chat.
   - On the client, `notification_service.dart`, `notification_hooks_service.dart`, and inbox-related screens reflect that the user may receive asynchronous engagement.

9. **Profile, transparency, and privacy controls**
   - The Flutter app has dedicated screens for profile, privacy, about, vault, relationship studio, and settings, which correspond to backend endpoints under `profile` and `ops`.
   - This indicates the system is designed around user agency: inspectable memory, reset/delete paths, and transparency controls are part of the product architecture, not add-ons.
   - The “memory vault” and “relationship studio” are especially important architectural surfaces because they expose internal state to the user.

10. **Ops and validation boundary**
   - `backend/api/ops.py`, `backend/inspect_db.py`, `backend/tests/`, and `backend/scripts/test_proactive.py` show there is explicit operational and test tooling around the backend.
   - The backend is intended to run on Railway, with `backend/Procfile` and `backend/railway.json` providing deployment configuration.
   - The README also notes live startup and smoke testing still matter, which means architecture exists, but runtime validation is a separate concern.

11. **Data and persistence**
   - The presence of `schema.sql`, memory store modules, and DB inspection tooling suggests a local relational persistence layer for user state, relationship state, and memory records.
   - Local/generated storage is treated as disposable or environment-specific; the repo hygiene notes mention avoiding committed database artifacts and a `chroma_db` directory, implying optional vector/memory persistence may exist in local development.
   - The key architectural point is that all durable state is backend-owned and pair-scoped, not embedded in the Flutter client.

12. **Cross-cutting runtime model**
   - The overall flow is: user authenticates in Flutter, the backend verifies identity, chat requests are enriched with memory and relationship context, the LLM generates a paced response, and the backend updates long-term state.
   - Separately, proactive systems can generate outbound engagement and notifications based on stored state and scheduling logic.
   - That gives the system three major boundaries: **client presentation**, **backend cognitive/memory orchestration**, and **persistent identity/state**.

Main entry points: [`frontend/companion_app/lib/services/api_service.dart`](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/api_service.dart) (API client), [`backend/main.py`](https://github.com/aakash-kr-7/sol/blob/main/backend/main.py) (API app), [`backend/core/context_builder.py`](https://github.com/aakash-kr-7/sol/blob/main/backend/core/context_builder.py) (Context builder), [`frontend/companion_app/lib/main.dart`](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/main.dart) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Flutter client"]
  node_frontend_main["App shell<br/>Flutter entry<br/>[main.dart]"]
  node_frontend_auth["Auth flow<br/>Firebase session<br/>[auth_service.dart]"]
  node_frontend_session["Session bootstrap<br/>Startup state"]
  node_frontend_api["API client<br/>Backend client<br/>[api_service.dart]"]
  node_frontend_burst["Burst playback<br/>Chat pacing"]
  node_frontend_notify["Notifications<br/>Push/inbox"]
  node_frontend_onboarding["Onboarding<br/>First-run UX"]
  node_frontend_chat["Chat screen<br/>Conversation UI<br/>[chat_screen.dart]"]
  node_frontend_inbox["Inbox<br/>Async engagement<br/>[inbox_screen.dart]"]
  node_frontend_vault["Memory vault<br/>Transparency UI"]
  node_frontend_profile["Privacy & profile<br/>User controls"]
end

subgraph group_backend["FastAPI backend"]
  node_backend_main["API app<br/>FastAPI root<br/>[main.py]"]
  node_backend_auth["Firebase auth<br/>Token verify<br/>[firebase.py]"]
  node_backend_chat_api["Chat API<br/>Route module<br/>[chat.py]"]
  node_backend_profile_api["Profile API<br/>Route module<br/>[profile.py]"]
  node_backend_onboarding_api["Onboarding API<br/>Route module<br/>[onboarding.py]"]
  node_backend_notifications_api["Notifications API<br/>Route module<br/>[notifications.py]"]
  node_backend_proactive_api["Proactive API<br/>Route module<br/>[proactive.py]"]
  node_backend_ops_api["Ops API<br/>Admin route<br/>[ops.py]"]
  node_backend_context["Context builder<br/>Chat context<br/>[context_builder.py]"]
  node_backend_llm["LLM core<br/>Model bridge<br/>[llm.py]"]
  node_backend_memory[("Memory pipeline<br/>Persistent memory<br/>[store.py]")]
  node_backend_personality["Persona registry<br/>Character data<br/>[registry.py]"]
  node_backend_proactive["Proactive engine<br/>Outbound logic"]
end

node_frontend_main -->|"bootstraps"| node_frontend_auth
node_frontend_main -->|"routes to"| node_frontend_onboarding
node_frontend_main -->|"opens"| node_frontend_chat
node_frontend_chat -->|"sends"| node_frontend_api
node_frontend_inbox -->|"listens to"| node_frontend_notify
node_frontend_profile -->|"surfaces"| node_frontend_vault
node_frontend_burst -->|"renders"| node_frontend_chat
node_frontend_api -->|"authenticates"| node_backend_auth
node_frontend_api -->|"calls"| node_backend_chat_api
node_frontend_api -->|"calls"| node_backend_profile_api
node_frontend_api -->|"calls"| node_backend_onboarding_api
node_frontend_api -->|"calls"| node_backend_notifications_api
node_frontend_api -->|"calls"| node_backend_proactive_api
node_frontend_api -->|"calls"| node_backend_ops_api
node_backend_main -->|"mounts"| node_backend_chat_api
node_backend_main -->|"mounts"| node_backend_profile_api
node_backend_main -->|"mounts"| node_backend_onboarding_api
node_backend_main -->|"mounts"| node_backend_notifications_api
node_backend_main -->|"mounts"| node_backend_proactive_api
node_backend_main -->|"mounts"| node_backend_ops_api
node_backend_chat_api -->|"builds"| node_backend_context
node_backend_context -->|"retrieves"| node_backend_memory
node_backend_context -->|"applies"| node_backend_personality
node_backend_context -->|"feeds"| node_backend_llm
node_backend_llm -->|"updates"| node_backend_memory
node_backend_proactive_api -->|"drives"| node_backend_proactive
node_backend_proactive -->|"consults"| node_backend_memory
node_backend_proactive -->|"emits"| node_backend_notifications_api

click node_frontend_main "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/main.dart"
click node_frontend_auth "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/auth_service.dart"
click node_frontend_session "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/session_bootstrap_service.dart"
click node_frontend_api "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/api_service.dart"
click node_frontend_burst "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/burst_playback_service.dart"
click node_frontend_notify "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/notification_service.dart"
click node_frontend_onboarding "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/onboarding_screen.dart"
click node_frontend_chat "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/chat_screen.dart"
click node_frontend_inbox "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/inbox_screen.dart"
click node_frontend_vault "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/memory_vault_screen.dart"
click node_frontend_profile "https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/privacy_screen.dart"
click node_backend_main "https://github.com/aakash-kr-7/sol/blob/main/backend/main.py"
click node_backend_auth "https://github.com/aakash-kr-7/sol/blob/main/backend/auth/firebase.py"
click node_backend_chat_api "https://github.com/aakash-kr-7/sol/blob/main/backend/api/chat.py"
click node_backend_profile_api "https://github.com/aakash-kr-7/sol/blob/main/backend/api/profile.py"
click node_backend_onboarding_api "https://github.com/aakash-kr-7/sol/blob/main/backend/api/onboarding.py"
click node_backend_notifications_api "https://github.com/aakash-kr-7/sol/blob/main/backend/api/notifications.py"
click node_backend_proactive_api "https://github.com/aakash-kr-7/sol/blob/main/backend/api/proactive.py"
click node_backend_ops_api "https://github.com/aakash-kr-7/sol/blob/main/backend/api/ops.py"
click node_backend_context "https://github.com/aakash-kr-7/sol/blob/main/backend/core/context_builder.py"
click node_backend_llm "https://github.com/aakash-kr-7/sol/blob/main/backend/core/llm.py"
click node_backend_memory "https://github.com/aakash-kr-7/sol/blob/main/backend/memory/store.py"
click node_backend_personality "https://github.com/aakash-kr-7/sol/blob/main/backend/personality/registry.py"
click node_backend_proactive "https://github.com/aakash-kr-7/sol/blob/main/backend/core/proactive_engine.py"

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_frontend_main,node_frontend_auth,node_frontend_session,node_frontend_api,node_frontend_burst,node_frontend_notify,node_frontend_onboarding,node_frontend_chat,node_frontend_inbox,node_frontend_vault,node_frontend_profile toneBlue
class node_backend_main,node_backend_auth,node_backend_chat_api,node_backend_profile_api,node_backend_onboarding_api,node_backend_notifications_api,node_backend_proactive_api,node_backend_ops_api,node_backend_context,node_backend_llm,node_backend_memory,node_backend_personality,node_backend_proactive toneAmber
```

## Components

### Flutter client

Cross-platform companion app UI and session layer.

- [App shell](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/main.dart): Flutter entry · Bootstraps the companion app and routes into the UI. · `frontend/companion_app/lib/main.dart`
- [Auth flow](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/auth_service.dart): Firebase session · Handles sign-in, device/session state, and biometric gating. · `frontend/companion_app/lib/services/auth_service.dart`
- [Session bootstrap](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/session_bootstrap_service.dart): Startup state · Establishes persisted user and companion session state after launch. · `frontend/companion_app/lib/services/session_bootstrap_service.dart`
- [API client](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/api_service.dart): Backend client · Central network boundary for chat, profile, onboarding, and notifications. · `frontend/companion_app/lib/services/api_service.dart`
- [Burst playback](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/burst_playback_service.dart): Chat pacing · Renders paced companion responses and typing-like interaction. · `frontend/companion_app/lib/services/burst_playback_service.dart`
- [Notifications](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/services/notification_service.dart): Push/inbox · Coordinates inbox-style prompts and device notification handling. · `frontend/companion_app/lib/services/notification_service.dart`
- [Onboarding](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/onboarding_screen.dart): First-run UX · Guides new users through setup and companion introduction. · `frontend/companion_app/lib/screens/onboarding_screen.dart`
- [Chat screen](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/chat_screen.dart): Conversation UI · Primary companion interaction surface for messages and pacing. · `frontend/companion_app/lib/screens/chat_screen.dart`
- [Inbox](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/inbox_screen.dart): Async engagement · Surfaces proactive outreach, notifications, and message entry points. · `frontend/companion_app/lib/screens/inbox_screen.dart`
- [Memory vault](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/memory_vault_screen.dart): Transparency UI · Exposes user-visible memory and stored relationship state. · `frontend/companion_app/lib/screens/memory_vault_screen.dart`
- [Privacy & profile](https://github.com/aakash-kr-7/sol/blob/main/frontend/companion_app/lib/screens/privacy_screen.dart): User controls · Contains privacy, about, settings, and relationship management surfaces. · `frontend/companion_app/lib/screens/privacy_screen.dart`

### FastAPI backend

API, orchestration, memory, and persistence services.

- [API app](https://github.com/aakash-kr-7/sol/blob/main/backend/main.py): FastAPI root · Composes the backend application and mounts the route modules. · `backend/main.py`
- [Firebase auth](https://github.com/aakash-kr-7/sol/blob/main/backend/auth/firebase.py): Token verify · Verifies Firebase identity before backend-scoped access is granted. · `backend/auth/firebase.py`
- [Chat API](https://github.com/aakash-kr-7/sol/blob/main/backend/api/chat.py): Route module · External chat entry point for companion conversation requests. · `backend/api/chat.py`
- [Profile API](https://github.com/aakash-kr-7/sol/blob/main/backend/api/profile.py): Route module · User-state and privacy-related backend entry point. · `backend/api/profile.py`
- [Onboarding API](https://github.com/aakash-kr-7/sol/blob/main/backend/api/onboarding.py): Route module · Supports first-run setup and companion initialization. · `backend/api/onboarding.py`
- [Notifications API](https://github.com/aakash-kr-7/sol/blob/main/backend/api/notifications.py): Route module · Delivers notification-facing backend actions and inbox signals. · `backend/api/notifications.py`
- [Proactive API](https://github.com/aakash-kr-7/sol/blob/main/backend/api/proactive.py): Route module · Exposes outbound engagement and scheduled companion behavior. · `backend/api/proactive.py`
- [Ops API](https://github.com/aakash-kr-7/sol/blob/main/backend/api/ops.py): Admin route · Operational visibility and maintenance entry point. · `backend/api/ops.py`
- [Context builder](https://github.com/aakash-kr-7/sol/blob/main/backend/core/context_builder.py): Chat context · Assembles rich conversation context from state and memory. · `backend/core/context_builder.py`
- [LLM core](https://github.com/aakash-kr-7/sol/blob/main/backend/core/llm.py): Model bridge · Generates companion responses from enriched context. · `backend/core/llm.py`
- [Memory pipeline](https://github.com/aakash-kr-7/sol/blob/main/backend/memory/store.py): Persistent memory · Extracts, consolidates, retrieves, and stores long-term memory and relationship signals. · `backend/memory/store.py`
- [Persona registry](https://github.com/aakash-kr-7/sol/blob/main/backend/personality/registry.py): Character data · Loads and serves companion character definitions and behavior profiles. · `backend/personality/registry.py`
- [Proactive engine](https://github.com/aakash-kr-7/sol/blob/main/backend/core/proactive_engine.py): Outbound logic · Schedules or triggers companion-initiated outreach. · `backend/core/proactive_engine.py`

## Connections

- App shell → Auth flow: bootstraps · App launch establishes authentication and session state.
- App shell → Onboarding: routes to · New users are guided into onboarding.
- App shell → Chat screen: opens · Authenticated users enter the main companion chat experience.
- Chat screen → API client: sends · Conversation and state changes are sent through the API client.
- Inbox → Notifications: listens to · Inbox UI reflects notification and proactive engagement state.
- Privacy & profile → Memory vault: surfaces · User controls expose inspectable memory and privacy surfaces.
- Burst playback → Chat screen: renders · Paced delivery shapes the conversation UI.
- API client → Firebase auth: authenticates · Client requests are accepted only after backend identity verification.
- API client → Chat API: calls · Chat traffic goes through the chat route module.
- API client → Profile API: calls · Profile, privacy, and user-state updates go through profile routes.
- API client → Onboarding API: calls · First-run setup uses onboarding routes.
- API client → Notifications API: calls · Notification state and inbox actions use notification routes.
- API client → Proactive API: calls · Proactive companion actions are requested through proactive routes.
- API client → Ops API: calls · Operational visibility is available through ops routes.
- API app → Chat API: mounts · Main app composes the chat route into FastAPI.
- API app → Profile API: mounts · Main app composes the profile route into FastAPI.
- API app → Onboarding API: mounts · Main app composes the onboarding route into FastAPI.
- API app → Notifications API: mounts · Main app composes the notifications route into FastAPI.
- API app → Proactive API: mounts · Main app composes the proactive route into FastAPI.
- API app → Ops API: mounts · Main app composes the ops route into FastAPI.
- Chat API → Context builder: builds · Chat requests are enriched before model generation.
- Context builder → Memory pipeline: retrieves · Context assembly pulls long-term memory and relationship signals.
- Context builder → Persona registry: applies · Context is shaped by the active companion persona.
- Context builder → LLM core: feeds · Prepared context is passed to the model layer.
- LLM core → Memory pipeline: updates · Generated interactions contribute to durable memory storage and consolidation.
- Proactive API → Proactive engine: drives · Route calls trigger proactive orchestration.
- Proactive engine → Memory pipeline: consults · Outbound behavior depends on stored memory and relationship state.
- Proactive engine → Notifications API: emits · Proactive events surface as notifications or inbox items.