# harshgupta38/shadow architecture

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

- Interactive diagram: https://gitdiagram.com/harshgupta38/shadow
- Repository: https://github.com/harshgupta38/shadow

## Overview

Shadow V2 is the current product: a personal AI planning and accountability app. A user works through goals, milestones and habits/tasks, gets a materialized daily plan, then tracks progress through journaling, reports and a spoken daily brief; the assistant can inspect and propose planning changes. The graph follows the README’s documented architecture and feature descriptions. Source excerpts are limited, so detailed domain-service calls and some integrations are shown only where the README explicitly documents them.

Main entry points: [`BackEnd_V2/app/api`](https://github.com/harshgupta38/shadow/tree/main/BackEnd_V2/app/api) (FastAPI API), [`BackEnd_V2/app/db/session.py`](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/db/session.py) (SQL database), [`BackEnd_V2/app/main.py`](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/main.py) (Background schedulers), [`BackEnd_V2/app/services/chat_service.py`](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/chat_service.py) (Tool-using assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Web app"]
  node_api["FastAPI API"]
  node_auth["Accounts and sessions<br/>[auth_service.py]"]
end

subgraph group_planning["Planning and progress"]
  node_goals["Goals and milestones<br/>[goals_service.py]"]
  node_habits["Habits<br/>[habits_service.py]"]
  node_tasks["Tasks and schedule<br/>[tasks_service.py]"]
  node_planner["Daily planning<br/>[planner_service.py]"]
  node_progress["Progress tracking"]
end

subgraph group_assistant["AI assistant"]
  node_assistant["Tool-using assistant<br/>[chat_service.py]"]
  node_llm["LLM service<br/>[service.py]"]
  node_memory["Persistent AI memory<br/>[memory_service.py]"]
end

subgraph group_insights["Accountability"]
  node_reports["Daily and weekly reports<br/>[report_service.py]"]
  node_brief["Daily brief and audio"]
  node_journal["Daily journal<br/>[journal_service.py]"]
  node_profile["Profile and dashboard"]
end

subgraph group_platform["Runtime platform"]
  node_notify["Notifications"]
  node_scheduler["Background schedulers<br/>[main.py]"]
  node_storage[("SQL database<br/>[session.py]")]
  node_providers["LLM providers"]
  node_delivery["Push, email, SSE<br/>[push_service.py]"]
  node_tts["Speech services<br/>[service.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"routes requests"| node_auth
node_api -->|"routes requests"| node_goals
node_api -->|"routes requests"| node_habits
node_api -->|"routes requests"| node_tasks
node_api -->|"routes requests"| node_planner
node_api -->|"routes requests"| node_progress
node_api -->|"routes requests"| node_assistant
node_api -->|"routes requests"| node_journal
node_api -->|"routes requests"| node_reports
node_api -->|"routes requests"| node_brief
node_api -->|"routes requests"| node_profile
node_api -->|"routes requests"| node_notify
node_planner -->|"reads and writes"| node_storage
node_assistant -->|"uses tools"| node_llm
node_assistant -->|"uses persistent memory"| node_memory
node_llm -->|"selects provider"| node_providers
node_reports -->|"reads and writes"| node_storage
node_brief -->|"generates speech"| node_tts
node_brief -->|"stores brief"| node_storage
node_journal -->|"stores entries"| node_storage
node_profile -->|"reads metrics"| node_storage
node_notify -->|"dispatches"| node_delivery
node_scheduler -->|"generates reports"| node_reports
node_scheduler -->|"dispatches notifications"| node_notify
node_scheduler -->|"backs up database"| node_storage

click node_frontend "https://github.com/harshgupta38/shadow/tree/main/FrontEnd_V2/src"
click node_api "https://github.com/harshgupta38/shadow/tree/main/BackEnd_V2/app/api"
click node_auth "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/auth_service.py"
click node_goals "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/goals_service.py"
click node_habits "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/habits_service.py"
click node_tasks "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/tasks_service.py"
click node_planner "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/planner_service.py"
click node_progress "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/track_progress_service.py"
click node_assistant "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/chat_service.py"
click node_llm "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/llm/service.py"
click node_memory "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/memory_service.py"
click node_reports "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/report_service.py"
click node_brief "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/daily_brief_service.py"
click node_journal "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/journal_service.py"
click node_profile "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/dashboard_service.py"
click node_notify "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/notifications_service.py"
click node_scheduler "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/main.py"
click node_storage "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/db/session.py"
click node_providers "https://github.com/harshgupta38/shadow/tree/main/BackEnd_V2/app/llm/providers"
click node_delivery "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/push_service.py"
click node_tts "https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/llm/tts/service.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,node_api,node_auth,node_user toneBlue
class node_goals,node_habits,node_tasks,node_planner,node_progress toneAmber
class node_assistant,node_llm,node_memory toneMint
class node_reports,node_brief,node_journal,node_profile toneRose
class node_notify,node_scheduler,node_storage,node_providers,node_delivery,node_tts toneIndigo
```

## Components

### User experience

- [Web app](https://github.com/harshgupta38/shadow/tree/main/FrontEnd_V2/src): `FrontEnd_V2/src`
- [FastAPI API](https://github.com/harshgupta38/shadow/tree/main/BackEnd_V2/app/api): `BackEnd_V2/app/api`
- [Accounts and sessions](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/auth_service.py): `BackEnd_V2/app/services/auth_service.py`

### Planning and progress

- [Goals and milestones](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/goals_service.py): `BackEnd_V2/app/services/goals_service.py`
- [Habits](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/habits_service.py): `BackEnd_V2/app/services/habits_service.py`
- [Tasks and schedule](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/tasks_service.py): `BackEnd_V2/app/services/tasks_service.py`
- [Daily planning](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/planner_service.py): `BackEnd_V2/app/services/planner_service.py`
- [Progress tracking](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/track_progress_service.py): `BackEnd_V2/app/services/track_progress_service.py`

### AI assistant

- [Tool-using assistant](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/chat_service.py): `BackEnd_V2/app/services/chat_service.py`
- [LLM service](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/llm/service.py): `BackEnd_V2/app/llm/service.py`
- [Persistent AI memory](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/memory_service.py): `BackEnd_V2/app/services/memory_service.py`

### Accountability

- [Daily and weekly reports](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/report_service.py): `BackEnd_V2/app/services/report_service.py`
- [Daily brief and audio](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/daily_brief_service.py): `BackEnd_V2/app/services/daily_brief_service.py`
- [Daily journal](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/journal_service.py): `BackEnd_V2/app/services/journal_service.py`
- [Profile and dashboard](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/dashboard_service.py): `BackEnd_V2/app/services/dashboard_service.py`

### Runtime platform

- [Notifications](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/notifications_service.py): `BackEnd_V2/app/services/notifications_service.py`
- [Background schedulers](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/main.py): `BackEnd_V2/app/main.py`
- [SQL database](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/db/session.py): `BackEnd_V2/app/db/session.py`
- [LLM providers](https://github.com/harshgupta38/shadow/tree/main/BackEnd_V2/app/llm/providers): `BackEnd_V2/app/llm/providers`
- [Push, email, SSE](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/services/push_service.py): `BackEnd_V2/app/services/push_service.py`
- [Speech services](https://github.com/harshgupta38/shadow/blob/main/BackEnd_V2/app/llm/tts/service.py): `BackEnd_V2/app/llm/tts/service.py`

### Other components

- **User**

## Connections

- User → Web app: uses
- Web app → FastAPI API: calls API
- FastAPI API → Accounts and sessions: routes requests
- FastAPI API → Goals and milestones: routes requests
- FastAPI API → Habits: routes requests
- FastAPI API → Tasks and schedule: routes requests
- FastAPI API → Daily planning: routes requests
- FastAPI API → Progress tracking: routes requests
- FastAPI API → Tool-using assistant: routes requests
- FastAPI API → Daily journal: routes requests
- FastAPI API → Daily and weekly reports: routes requests
- FastAPI API → Daily brief and audio: routes requests
- FastAPI API → Profile and dashboard: routes requests
- FastAPI API → Notifications: routes requests
- Daily planning → SQL database: reads and writes
- Tool-using assistant → LLM service: uses tools
- Tool-using assistant → Persistent AI memory: uses persistent memory
- LLM service → LLM providers: selects provider
- Daily and weekly reports → SQL database: reads and writes
- Daily brief and audio → Speech services: generates speech
- Daily brief and audio → SQL database: stores brief
- Daily journal → SQL database: stores entries
- Profile and dashboard → SQL database: reads metrics
- Notifications → Push, email, SSE: dispatches
- Background schedulers → Daily and weekly reports: generates reports
- Background schedulers → Notifications: dispatches notifications
- Background schedulers → SQL database: backs up database (evidence: `BackEnd_V2/app/main.py`)