# stephenwzkong/personal_assistant architecture

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

- Interactive diagram: https://gitdiagram.com/stephenwzkong/personal_assistant
- Repository: https://github.com/stephenwzkong/personal_assistant

## Overview

#### Purpose and Entry Points
Personal Assistant is a full-stack, domain-oriented assistant for finance, productivity, social, wellness, calendar, tasks, and conversational support. Backend entry points are the API app and runner: `src/assistant/api/main.py`, `src/assistant/runner.py`. The browser client starts at `src/assistant/frontend/src/main.tsx` and composes its application shell in `src/assistant/frontend/src/app/App.tsx`.

#### API and Client Boundary
The Python API exposes chat, session, calendar, and task boundaries through `src/assistant/api/routes/chat.py`, `src/assistant/api/routes/session.py`, and `src/assistant/api/routes/calendar.py`. The React/Vite frontend calls these boundaries through stateful hooks—`src/assistant/frontend/src/hooks/useChat.ts`, `src/assistant/frontend/src/hooks/useSession.ts`, and `src/assistant/frontend/src/hooks/useTasks.ts`—rather than embedding backend logic in page components.

#### Agent Routing and Execution
`src/assistant/agents/root_orchestrator.py` is the primary control point for interpreting user requests and selecting specialist handling. Domain routers partition multi-agent behavior for productivity, social, and wellness: `src/assistant/agents/productivity/productivity_router.py`, `src/assistant/agents/social/social_router.py`, and `src/assistant/agents/wellness/wellness_router.py`. Specialists then cover discrete concerns such as finance, tasks, fitness, meals, sleep, reading, school, relationships, and news.

#### Tool and Schema Layer
Agents perform application actions through domain tools, which form the operational boundary to persistence and external capabilities: `src/assistant/tools/shared/calendar_tools.py`, `src/assistant/tools/productivity/task_tools.py`, and `src/assistant/tools/shared/memory_tools.py`. Typed/domain data definitions are centralized under `src/assistant/schema/`, notably `src/assistant/schema/shared_schemas.py`, `src/assistant/schema/task_schemas.py`, and `src/assistant/schema/memory_schemas.py`. This separates conversational decisions from data operations.

#### Memory and Cloud Persistence
Conversation/session memory is handled by a dedicated subsystem: `src/assistant/memory/service.py`, `src/assistant/memory/firestore_session_service.py`, and `src/assistant/memory/cross_domain.py`. The repository also includes a BigQuery integration at `src/assistant/db/bq_client.py`. Google Cloud authentication and project configuration are required; the runtime expects Google credentials plus `GOOGLE_API_KEY` and `GOOGLE_CLOUD_PROJECT`.

#### Prompt, Skill, and Knowledge Assets
Behavior is largely data-driven through versioned prompt and skill documents. The orchestrator prompt is `src/assistant/prompts/root_orchestrator.md`; reusable prompt assembly is in `src/assistant/prompts/loader.py`; skill loading is in `src/assistant/skills/loader.py`. Domain guidance exists as skills and reference material, e.g. `src/assistant/skills/finance/SKILL.md` and `src/assistant/knowledge/wellness/fitness.md`, allowing domain behavior to evolve independently of routing code.

#### Runtime and Delivery Shape
The backend is Python with dependencies declared in `pyproject.toml` and `src/assistant/requirements.txt`; it is containerized by `src/assistant/Dockerfile`. The frontend is a TypeScript React application with Vite configuration in `src/assistant/frontend/vite.config.ts`. The central end-to-end flow is: UI interaction → API route → root/domain agent routing → tools, memory, and cloud data services → agent response and updated client state.

Main entry points: [`src/assistant/agents/root_orchestrator.py`](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/agents/root_orchestrator.py) (Root orchestrator), [`src/assistant/tools/shared/calendar_tools.py`](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/tools/shared/calendar_tools.py) (Domain tools), [`src/assistant/api/routes/chat.py`](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/api/routes/chat.py) (Chat, session, calendar routes), [`src/assistant/frontend/src/main.tsx`](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/src/main.tsx) (Frontend entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_frontend_main["Frontend entry<br/>React entry<br/>[main.tsx]"]
  node_app_shell["Application shell<br/>React app<br/>[App.tsx]"]
  node_client_hooks["Stateful API hooks<br/>React hooks<br/>[useChat.ts]"]
  node_frontend_build["Vite build<br/>frontend build<br/>[vite.config.ts]"]
end

subgraph group_api["Python API"]
  node_api_app["API application<br/>Python API<br/>[main.py]"]
  node_api_routes["Chat, session, calendar routes<br/>API routes<br/>[chat.py]"]
  node_runner["Backend runner<br/>runtime entry<br/>[runner.py]"]
  node_backend_container["Backend container<br/>deployment"]
end

subgraph group_agents["Agent Runtime"]
  node_root_orchestrator{{"Root orchestrator<br/>agent controller"}}
  node_domain_routers["Domain routers<br/>agent routers"]
  node_specialist_agents["Specialist agents<br/>domain agents"]
  node_domain_tools["Domain tools<br/>action boundary<br/>[calendar_tools.py]"]
end

subgraph group_data["Data and Assets"]
  node_schemas["Domain schemas<br/>typed models<br/>[shared_schemas.py]"]
  node_memory_service["Memory service<br/>memory subsystem<br/>[service.py]"]
  node_firestore[("Firestore sessions<br/>cloud persistence")]
  node_bigquery[("BigQuery client<br/>cloud analytics<br/>[bq_client.py]")]
  node_orchestrator_prompt["Orchestrator prompt<br/>prompt asset"]
  node_prompt_loader["Prompt loader<br/>prompt assembly<br/>[loader.py]"]
  node_skill_loader["Skill loader<br/>skill assembly<br/>[loader.py]"]
  node_skills_knowledge["Skills and knowledge<br/>domain guidance<br/>[SKILL.md]"]
end

node_frontend_main -->|"mounts"| node_app_shell
node_app_shell -->|"uses"| node_client_hooks
node_client_hooks -->|"calls"| node_api_routes
node_api_app -->|"exposes"| node_api_routes
node_runner -->|"runs"| node_root_orchestrator
node_api_routes -->|"dispatches requests"| node_root_orchestrator
node_root_orchestrator -->|"routes by domain"| node_domain_routers
node_domain_routers -->|"selects"| node_specialist_agents
node_root_orchestrator -->|"delegates"| node_specialist_agents
node_specialist_agents -->|"performs actions"| node_domain_tools
node_domain_tools -->|"uses types"| node_schemas
node_domain_tools -->|"reads and writes memory"| node_memory_service
node_memory_service -->|"persists sessions"| node_firestore
node_domain_tools -->|"accesses cloud data"| node_bigquery
node_prompt_loader -->|"loads"| node_orchestrator_prompt
node_root_orchestrator -->|"assembles prompt"| node_prompt_loader
node_skill_loader -->|"loads"| node_skills_knowledge
node_specialist_agents -->|"uses guidance"| node_skill_loader
node_backend_container -.->|"packages"| node_api_app
node_frontend_build -.->|"builds"| node_frontend_main

click node_frontend_main "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/src/main.tsx"
click node_app_shell "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/src/app/App.tsx"
click node_client_hooks "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/src/hooks/useChat.ts"
click node_api_app "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/api/main.py"
click node_api_routes "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/api/routes/chat.py"
click node_runner "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/runner.py"
click node_root_orchestrator "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/agents/root_orchestrator.py"
click node_domain_routers "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/agents/productivity/productivity_router.py"
click node_domain_tools "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/tools/shared/calendar_tools.py"
click node_schemas "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/schema/shared_schemas.py"
click node_memory_service "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/memory/service.py"
click node_firestore "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/memory/firestore_session_service.py"
click node_bigquery "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/db/bq_client.py"
click node_orchestrator_prompt "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/prompts/root_orchestrator.md"
click node_prompt_loader "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/prompts/loader.py"
click node_skill_loader "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/skills/loader.py"
click node_skills_knowledge "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/skills/finance/SKILL.md"
click node_backend_container "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/Dockerfile"
click node_frontend_build "https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/vite.config.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_frontend_main,node_app_shell,node_client_hooks,node_frontend_build toneBlue
class node_api_app,node_api_routes,node_runner,node_backend_container toneAmber
class node_root_orchestrator,node_domain_routers,node_specialist_agents,node_domain_tools toneMint
class node_schemas,node_memory_service,node_firestore,node_bigquery,node_orchestrator_prompt,node_prompt_loader,node_skill_loader,node_skills_knowledge toneRose
```

## Components

### Browser Client

- [Frontend entry](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/src/main.tsx): React entry · `src/assistant/frontend/src/main.tsx`
- [Application shell](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/src/app/App.tsx): React app · `src/assistant/frontend/src/app/App.tsx`
- [Stateful API hooks](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/src/hooks/useChat.ts): React hooks · Chat, session, and task state call backend boundaries. · `src/assistant/frontend/src/hooks/useChat.ts`
- [Vite build](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/frontend/vite.config.ts): frontend build · `src/assistant/frontend/vite.config.ts`

### Python API

- [API application](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/api/main.py): Python API · `src/assistant/api/main.py`
- [Chat, session, calendar routes](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/api/routes/chat.py): API routes · `src/assistant/api/routes/chat.py`
- [Backend runner](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/runner.py): runtime entry · `src/assistant/runner.py`
- [Backend container](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/Dockerfile): deployment · `src/assistant/Dockerfile`

### Agent Runtime

- [Root orchestrator](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/agents/root_orchestrator.py): agent controller · Interprets requests and selects domain handling. · `src/assistant/agents/root_orchestrator.py`
- [Domain routers](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/agents/productivity/productivity_router.py): agent routers · Productivity, social, and wellness routing. · `src/assistant/agents/productivity/productivity_router.py`
- **Specialist agents**: domain agents · Finance, tasks, fitness, meals, sleep, reading, school, relationships, and news.
- [Domain tools](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/tools/shared/calendar_tools.py): action boundary · Calendar, task, and memory operations. · `src/assistant/tools/shared/calendar_tools.py`

### Data and Assets

- [Domain schemas](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/schema/shared_schemas.py): typed models · `src/assistant/schema/shared_schemas.py`
- [Memory service](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/memory/service.py): memory subsystem · Manages conversation, session, and cross-domain memory. · `src/assistant/memory/service.py`
- [Firestore sessions](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/memory/firestore_session_service.py): cloud persistence · `src/assistant/memory/firestore_session_service.py`
- [BigQuery client](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/db/bq_client.py): cloud analytics · `src/assistant/db/bq_client.py`
- [Orchestrator prompt](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/prompts/root_orchestrator.md): prompt asset · `src/assistant/prompts/root_orchestrator.md`
- [Prompt loader](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/prompts/loader.py): prompt assembly · `src/assistant/prompts/loader.py`
- [Skill loader](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/skills/loader.py): skill assembly · `src/assistant/skills/loader.py`
- [Skills and knowledge](https://github.com/stephenwzkong/personal_assistant/blob/main/src/assistant/skills/finance/SKILL.md): domain guidance · Versioned skills and reference material guide domain behavior. · `src/assistant/skills/finance/SKILL.md`

## Connections

- Frontend entry → Application shell: mounts
- Application shell → Stateful API hooks: uses
- Stateful API hooks → Chat, session, calendar routes: calls
- API application → Chat, session, calendar routes: exposes
- Backend runner → Root orchestrator: runs
- Chat, session, calendar routes → Root orchestrator: dispatches requests
- Root orchestrator → Domain routers: routes by domain
- Domain routers → Specialist agents: selects
- Root orchestrator → Specialist agents: delegates
- Specialist agents → Domain tools: performs actions
- Domain tools → Domain schemas: uses types
- Domain tools → Memory service: reads and writes memory
- Memory service → Firestore sessions: persists sessions
- Domain tools → BigQuery client: accesses cloud data
- Prompt loader → Orchestrator prompt: loads
- Root orchestrator → Prompt loader: assembles prompt
- Skill loader → Skills and knowledge: loads
- Specialist agents → Skill loader: uses guidance
- Backend container → API application: packages
- Vite build → Frontend entry: builds