aakash-kr-7/sol

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.