# neruaka/passion-project architecture

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

- Interactive diagram: https://gitdiagram.com/neruaka/passion-project
- Repository: https://github.com/neruaka/passion-project
- Video tour (about a minute): https://gitdiagram.com/neruaka/passion-project/video

## Overview

PASSION-FR is a self-hosted personal AI system; the current implemented focus is fitness. A user accesses the dashboard and API, fitness data can sync from Hevy, and analysis produces records, findings, recovery information, and period statistics. The README also describes brain/chat, memory, nutrition, health ingestion, and notifications, though several are planned or unsampled; those are shown conservatively. The sampled source confirms the Hevy sync and nightly analysis ownership, but not all API-to-service wiring.

Main entry points: [`backend/src/services/fitness/analysis_runner.py`](https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/analysis_runner.py) (Analysis runner), [`backend/src/db/session.py`](https://github.com/neruaka/passion-project/blob/master/backend/src/db/session.py) (PostgreSQL), [`backend/src/jobs/tasks.py`](https://github.com/neruaka/passion-project/blob/master/backend/src/jobs/tasks.py) (Scheduled tasks), [`backend/src/api/router.py`](https://github.com/neruaka/passion-project/blob/master/backend/src/api/router.py) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_chat_socket["Chat interface<br/>[chat-socket.ts]"]
end

subgraph group_api["Backend API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_auth_api["Authentication<br/>[auth.py]"]
  node_workouts_api["Workout API<br/>[workouts.py]"]
  node_analysis_api["Analysis API<br/>[analysis.py]"]
end

subgraph group_fitness["Fitness domain"]
  node_fitness_services["Fitness services"]
  node_analysis_runner["Analysis runner<br/>[analysis_runner.py]"]
  node_pr_detection["PR detection<br/>[pr_detection.py]"]
  node_plateau["Plateau detection<br/>[plateau.py]"]
  node_recovery["Recovery status<br/>[recovery.py]"]
  node_stats["Period statistics<br/>[stats.py]"]
  node_targets["Training targets<br/>[targets.py]"]
  node_workout_repo["Workout repository<br/>[workouts.py]"]
  node_analysis_repo["Analysis repository<br/>[analysis.py]"]
  node_workout_models["Workout records<br/>[workouts.py]"]
  node_analysis_models["Analysis records<br/>[analysis.py]"]
  node_targets_models["Target records<br/>[targets.py]"]
  node_health_models["Health records<br/>[health.py]"]
end

subgraph group_platform["Runtime platform"]
  node_celery_tasks["Scheduled tasks<br/>[tasks.py]"]
  node_database[("PostgreSQL<br/>[session.py]")]
end

subgraph group_ai["AI and integrations"]
  node_brain["Agent orchestration<br/>[graph.py]"]
  node_memory[("Long-term memory")]
  node_llm_router["LLM routing<br/>[router.py]"]
  node_hevy_client["Hevy MCP client<br/>[hevy.py]"]
  node_cronometer["Cronometer integration"]
  node_ntfy["Push notifications<br/>[ntfy.py]"]
end

node_user(("User"))
node_hevy_service{{"Hevy"}}
node_cronometer_service{{"Cronometer"}}
node_llm_providers{{"LLM providers"}}
node_ntfy_service{{"ntfy.sh"}}

node_user -->|"uses"| node_dashboard
node_dashboard -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_app
node_dashboard -->|"opens chat"| node_chat_socket
node_app -->|"mounts"| node_api_router
node_api_router -->|"dispatches"| node_auth_api
node_api_router -->|"dispatches"| node_workouts_api
node_api_router -->|"dispatches"| node_analysis_api
node_celery_tasks -->|"builds client"| node_hevy_client
node_celery_tasks -->|"runs sync"| node_fitness_services
node_fitness_services -->|"fetches workouts"| node_hevy_client
node_hevy_client -->|"calls MCP"| node_hevy_service
node_celery_tasks -->|"runs nightly"| node_analysis_runner
node_analysis_runner -->|"loads and saves"| node_analysis_repo
node_analysis_runner -->|"loads sets"| node_workout_repo
node_analysis_runner -->|"detects records"| node_pr_detection
node_analysis_runner -->|"detects stalls"| node_plateau
node_analysis_runner -->|"computes status"| node_recovery
node_analysis_runner -->|"aggregates periods"| node_stats
node_analysis_runner -->|"checks progress"| node_targets
node_workout_repo -->|"reads workouts"| node_database
node_analysis_repo -->|"reads and writes"| node_database
node_database -->|"stores"| node_workout_models
node_database -->|"stores"| node_analysis_models
node_database -->|"stores"| node_targets_models
node_database -->|"stores"| node_health_models
node_chat_socket -.->|"chat transport"| node_app
node_brain -.->|"routes reasoning"| node_llm_router
node_brain -.->|"retrieves context"| node_memory
node_llm_router -.->|"calls models"| node_llm_providers
node_cronometer -.->|"syncs nutrition"| node_cronometer_service
node_celery_tasks -->|"alerts on failure"| node_ntfy
node_ntfy -->|"sends notification"| node_ntfy_service

click node_dashboard "https://github.com/neruaka/passion-project/blob/master/frontend/src/app/page.tsx"
click node_api_client "https://github.com/neruaka/passion-project/blob/master/frontend/src/lib/api/client.ts"
click node_chat_socket "https://github.com/neruaka/passion-project/blob/master/frontend/src/lib/ws/chat-socket.ts"
click node_app "https://github.com/neruaka/passion-project/blob/master/backend/src/main.py"
click node_api_router "https://github.com/neruaka/passion-project/blob/master/backend/src/api/router.py"
click node_auth_api "https://github.com/neruaka/passion-project/blob/master/backend/src/api/v1/auth.py"
click node_workouts_api "https://github.com/neruaka/passion-project/blob/master/backend/src/api/v1/workouts.py"
click node_analysis_api "https://github.com/neruaka/passion-project/blob/master/backend/src/api/v1/analysis.py"
click node_fitness_services "https://github.com/neruaka/passion-project/tree/master/backend/src/services/fitness"
click node_analysis_runner "https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/analysis_runner.py"
click node_pr_detection "https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/pr_detection.py"
click node_plateau "https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/plateau.py"
click node_recovery "https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/recovery.py"
click node_stats "https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/stats.py"
click node_targets "https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/targets.py"
click node_workout_repo "https://github.com/neruaka/passion-project/blob/master/backend/src/repositories/workouts.py"
click node_analysis_repo "https://github.com/neruaka/passion-project/blob/master/backend/src/repositories/analysis.py"
click node_workout_models "https://github.com/neruaka/passion-project/blob/master/backend/src/models/workouts.py"
click node_analysis_models "https://github.com/neruaka/passion-project/blob/master/backend/src/models/analysis.py"
click node_targets_models "https://github.com/neruaka/passion-project/blob/master/backend/src/models/targets.py"
click node_celery_tasks "https://github.com/neruaka/passion-project/blob/master/backend/src/jobs/tasks.py"
click node_database "https://github.com/neruaka/passion-project/blob/master/backend/src/db/session.py"
click node_health_models "https://github.com/neruaka/passion-project/blob/master/backend/src/models/health.py"
click node_brain "https://github.com/neruaka/passion-project/blob/master/backend/src/brain/graph.py"
click node_memory "https://github.com/neruaka/passion-project/tree/master/backend/src/memory"
click node_llm_router "https://github.com/neruaka/passion-project/blob/master/backend/src/llm/router.py"
click node_hevy_client "https://github.com/neruaka/passion-project/blob/master/backend/src/integrations/mcp/hevy.py"
click node_cronometer "https://github.com/neruaka/passion-project/tree/master/backend/src/integrations/mcp"
click node_ntfy "https://github.com/neruaka/passion-project/blob/master/backend/src/integrations/external/ntfy.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_dashboard,node_api_client,node_chat_socket,node_user toneBlue
class node_app,node_api_router,node_auth_api,node_workouts_api,node_analysis_api toneAmber
class node_fitness_services,node_analysis_runner,node_pr_detection,node_plateau,node_recovery,node_stats,node_targets,node_workout_repo,node_analysis_repo,node_workout_models,node_analysis_models,node_targets_models,node_health_models toneMint
class node_celery_tasks,node_database toneRose
class node_brain,node_memory,node_llm_router,node_hevy_client,node_cronometer,node_ntfy,node_hevy_service,node_cronometer_service,node_llm_providers,node_ntfy_service toneIndigo
```

## Components

### User experience

- [Dashboard](https://github.com/neruaka/passion-project/blob/master/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [API client](https://github.com/neruaka/passion-project/blob/master/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`
- [Chat interface](https://github.com/neruaka/passion-project/blob/master/frontend/src/lib/ws/chat-socket.ts): `frontend/src/lib/ws/chat-socket.ts`

### Backend API

- [FastAPI app](https://github.com/neruaka/passion-project/blob/master/backend/src/main.py): `backend/src/main.py`
- [API router](https://github.com/neruaka/passion-project/blob/master/backend/src/api/router.py): `backend/src/api/router.py`
- [Authentication](https://github.com/neruaka/passion-project/blob/master/backend/src/api/v1/auth.py): `backend/src/api/v1/auth.py`
- [Workout API](https://github.com/neruaka/passion-project/blob/master/backend/src/api/v1/workouts.py): `backend/src/api/v1/workouts.py`
- [Analysis API](https://github.com/neruaka/passion-project/blob/master/backend/src/api/v1/analysis.py): `backend/src/api/v1/analysis.py`

### Fitness domain

- [Fitness services](https://github.com/neruaka/passion-project/tree/master/backend/src/services/fitness): `backend/src/services/fitness`
- [Analysis runner](https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/analysis_runner.py): `backend/src/services/fitness/analysis_runner.py`
- [PR detection](https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/pr_detection.py): `backend/src/services/fitness/pr_detection.py`
- [Plateau detection](https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/plateau.py): `backend/src/services/fitness/plateau.py`
- [Recovery status](https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/recovery.py): `backend/src/services/fitness/recovery.py`
- [Period statistics](https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/stats.py): `backend/src/services/fitness/stats.py`
- [Training targets](https://github.com/neruaka/passion-project/blob/master/backend/src/services/fitness/targets.py): `backend/src/services/fitness/targets.py`
- [Workout repository](https://github.com/neruaka/passion-project/blob/master/backend/src/repositories/workouts.py): `backend/src/repositories/workouts.py`
- [Analysis repository](https://github.com/neruaka/passion-project/blob/master/backend/src/repositories/analysis.py): `backend/src/repositories/analysis.py`
- [Workout records](https://github.com/neruaka/passion-project/blob/master/backend/src/models/workouts.py): `backend/src/models/workouts.py`
- [Analysis records](https://github.com/neruaka/passion-project/blob/master/backend/src/models/analysis.py): `backend/src/models/analysis.py`
- [Target records](https://github.com/neruaka/passion-project/blob/master/backend/src/models/targets.py): `backend/src/models/targets.py`
- [Health records](https://github.com/neruaka/passion-project/blob/master/backend/src/models/health.py): `backend/src/models/health.py`

### Runtime platform

- [Scheduled tasks](https://github.com/neruaka/passion-project/blob/master/backend/src/jobs/tasks.py): `backend/src/jobs/tasks.py`
- [PostgreSQL](https://github.com/neruaka/passion-project/blob/master/backend/src/db/session.py): `backend/src/db/session.py`

### AI and integrations

- [Agent orchestration](https://github.com/neruaka/passion-project/blob/master/backend/src/brain/graph.py): `backend/src/brain/graph.py`
- [Long-term memory](https://github.com/neruaka/passion-project/tree/master/backend/src/memory): `backend/src/memory`
- [LLM routing](https://github.com/neruaka/passion-project/blob/master/backend/src/llm/router.py): `backend/src/llm/router.py`
- [Hevy MCP client](https://github.com/neruaka/passion-project/blob/master/backend/src/integrations/mcp/hevy.py): `backend/src/integrations/mcp/hevy.py`
- [Cronometer integration](https://github.com/neruaka/passion-project/tree/master/backend/src/integrations/mcp): `backend/src/integrations/mcp`
- [Push notifications](https://github.com/neruaka/passion-project/blob/master/backend/src/integrations/external/ntfy.py): `backend/src/integrations/external/ntfy.py`

### Other components

- **User**
- **Hevy**
- **Cronometer**
- **LLM providers**
- **ntfy.sh**

## Connections

- User → Dashboard: uses
- Dashboard → API client: requests
- API client → FastAPI app: calls API
- Dashboard → Chat interface: opens chat
- FastAPI app → API router: mounts
- API router → Authentication: dispatches
- API router → Workout API: dispatches
- API router → Analysis API: dispatches
- Scheduled tasks → Hevy MCP client: builds client
- Scheduled tasks → Fitness services: runs sync
- Fitness services → Hevy MCP client: fetches workouts
- Hevy MCP client → Hevy: calls MCP
- Scheduled tasks → Analysis runner: runs nightly
- Analysis runner → Analysis repository: loads and saves
- Analysis runner → Workout repository: loads sets
- Analysis runner → PR detection: detects records
- Analysis runner → Plateau detection: detects stalls
- Analysis runner → Recovery status: computes status
- Analysis runner → Period statistics: aggregates periods
- Analysis runner → Training targets: checks progress
- Workout repository → PostgreSQL: reads workouts
- Analysis repository → PostgreSQL: reads and writes
- PostgreSQL → Workout records: stores
- PostgreSQL → Analysis records: stores
- PostgreSQL → Target records: stores
- PostgreSQL → Health records: stores
- Chat interface → FastAPI app: chat transport
- Agent orchestration → LLM routing: routes reasoning
- Agent orchestration → Long-term memory: retrieves context
- LLM routing → LLM providers: calls models
- Cronometer integration → Cronometer: syncs nutrition
- Scheduled tasks → Push notifications: alerts on failure
- Push notifications → ntfy.sh: sends notification