# sanych44474/trix architecture

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

- Interactive diagram: https://gitdiagram.com/sanych44474/trix
- Repository: https://github.com/sanych44474/trix
- Video tour (about a minute): https://gitdiagram.com/sanych44474/trix/video

## Overview

trix is an AI strength-and-nutrition coach delivered through Telegram and a Telegram Mini App. The main journey is onboarding and plan creation, workout delivery and logging, then progression, nutrition/recovery tracking and coaching follow-up. Human trainers can manage clients alongside the solo-athlete flow; motivation, reminders and owner tools are additional capabilities. The README documents the high-level runtime wiring, while sampled source confirms selected bot, AI and D1 relationships; unsampled feature links are omitted where their callers are not evidenced.

Main entry points: [`src/bot/router.ts`](https://github.com/sanych44474/trix/blob/main/src/bot/router.ts) (Bot routing), [`src/index.ts`](https://github.com/sanych44474/trix/blob/main/src/index.ts) (Worker runtime), [`src/adapters/d1/v2Users.ts`](https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Users.ts) (User records), [`apps/mini-app/src/App.tsx`](https://github.com/sanych44474/trix/blob/main/apps/mini-app/src/App.tsx) (Mini App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User surfaces"]
  node_telegram["Telegram chat"]
  node_miniapp["Mini App<br/>[App.tsx]"]
  node_bot["Bot routing<br/>[router.ts]"]
end

subgraph group_coach["Coaching workflows"]
  node_onboard["Onboarding<br/>[onboarding.ts]"]
  node_plans["Training plans<br/>[plan.ts]"]
  node_nutrition["Nutrition coaching<br/>[nutritionLog.ts]"]
  node_trainer_tools["Trainer tools<br/>[trainer.ts]"]
end

subgraph group_tracking["Training and wellbeing"]
  node_workout["Workout logger<br/>[useSession.ts]"]
  node_progression["Progression logic<br/>[progression.ts]"]
  node_wellbeing["Body and recovery<br/>[v2Tracking.ts]"]
  node_community["Gamification<br/>[challenges.ts]"]
end

subgraph group_platform["Runtime services"]
  node_worker["Worker runtime<br/>[index.ts]"]
  node_ai["AI provider chain<br/>[index.ts]"]
  node_scheduler["Scheduled coaching<br/>[scheduler.ts]"]
end

subgraph group_storage["Persistence"]
  node_d1[("D1 database")]
  node_users["User records<br/>[v2Users.ts]"]
  node_plan_store["Plan records<br/>[v2Plans.ts]"]
  node_workout_store["Workout records<br/>[v2Workouts.ts]"]
  node_nutrition_store["Nutrition records<br/>[v2Nutrition.ts]"]
  node_trainer_store["Trainer records<br/>[v2Trainer.ts]"]
end

node_athlete(("Athlete"))
node_trainer(("Human trainer"))

node_athlete -->|"messages"| node_telegram
node_athlete -->|"uses"| node_miniapp
node_trainer -->|"manages clients"| node_telegram
node_telegram -->|"webhook"| node_worker
node_miniapp -->|"API requests"| node_worker
node_worker -->|"routes chat"| node_bot
node_bot -->|"starts interview"| node_onboard
node_bot -->|"handles plans"| node_plans
node_bot -->|"requests coaching"| node_ai
node_bot -->|"loads user"| node_users
node_onboard -.->|"updates profile"| node_users
node_plans -->|"saves plan"| node_plan_store
node_miniapp -->|"renders logger"| node_workout
node_workout -.->|"saves sessions"| node_workout_store
node_workout -.->|"supports progression"| node_progression
node_nutrition -->|"parses meals"| node_ai
node_nutrition -->|"stores food logs"| node_nutrition_store
node_wellbeing -.->|"reads and writes"| node_d1
node_trainer_tools -->|"manages relationships"| node_trainer_store
node_trainer_tools -->|"updates clients"| node_users
node_community -.->|"records activity"| node_d1
node_worker -->|"runs cron"| node_scheduler
node_scheduler -.->|"reads and writes"| node_d1
node_users -->|"persists accounts"| node_d1
node_plan_store -->|"persists plans"| node_d1
node_workout_store -.->|"persists workouts"| node_d1
node_nutrition_store -->|"persists nutrition"| node_d1
node_trainer_store -.->|"persists trainer data"| node_d1

click node_miniapp "https://github.com/sanych44474/trix/blob/main/apps/mini-app/src/App.tsx"
click node_worker "https://github.com/sanych44474/trix/blob/main/src/index.ts"
click node_bot "https://github.com/sanych44474/trix/blob/main/src/bot/router.ts"
click node_onboard "https://github.com/sanych44474/trix/blob/main/src/bot/onboarding.ts"
click node_plans "https://github.com/sanych44474/trix/blob/main/src/bot/plan.ts"
click node_ai "https://github.com/sanych44474/trix/blob/main/src/ai/index.ts"
click node_workout "https://github.com/sanych44474/trix/blob/main/apps/mini-app/src/train/useSession.ts"
click node_progression "https://github.com/sanych44474/trix/blob/main/src/domain/progression.ts"
click node_nutrition "https://github.com/sanych44474/trix/blob/main/src/features/nutrition/nutritionLog.ts"
click node_wellbeing "https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Tracking.ts"
click node_trainer_tools "https://github.com/sanych44474/trix/blob/main/src/features/trainer/trainer.ts"
click node_community "https://github.com/sanych44474/trix/blob/main/src/features/gamification/challenges.ts"
click node_scheduler "https://github.com/sanych44474/trix/blob/main/src/scheduler.ts"
click node_users "https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Users.ts"
click node_plan_store "https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Plans.ts"
click node_workout_store "https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Workouts.ts"
click node_nutrition_store "https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Nutrition.ts"
click node_trainer_store "https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Trainer.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_telegram,node_miniapp,node_bot toneBlue
class node_onboard,node_plans,node_nutrition,node_trainer_tools toneAmber
class node_workout,node_progression,node_wellbeing,node_community toneMint
class node_worker,node_ai,node_scheduler toneRose
class node_d1,node_users,node_plan_store,node_workout_store,node_nutrition_store,node_trainer_store,node_athlete,node_trainer toneIndigo
```

## Components

### User surfaces

- **Telegram chat**
- [Mini App](https://github.com/sanych44474/trix/blob/main/apps/mini-app/src/App.tsx): `apps/mini-app/src/App.tsx`
- [Bot routing](https://github.com/sanych44474/trix/blob/main/src/bot/router.ts): `src/bot/router.ts`

### Coaching workflows

- [Onboarding](https://github.com/sanych44474/trix/blob/main/src/bot/onboarding.ts): `src/bot/onboarding.ts`
- [Training plans](https://github.com/sanych44474/trix/blob/main/src/bot/plan.ts): `src/bot/plan.ts`
- [Nutrition coaching](https://github.com/sanych44474/trix/blob/main/src/features/nutrition/nutritionLog.ts): `src/features/nutrition/nutritionLog.ts`
- [Trainer tools](https://github.com/sanych44474/trix/blob/main/src/features/trainer/trainer.ts): `src/features/trainer/trainer.ts`

### Training and wellbeing

- [Workout logger](https://github.com/sanych44474/trix/blob/main/apps/mini-app/src/train/useSession.ts): `apps/mini-app/src/train/useSession.ts`
- [Progression logic](https://github.com/sanych44474/trix/blob/main/src/domain/progression.ts): `src/domain/progression.ts`
- [Body and recovery](https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Tracking.ts): `src/adapters/d1/v2Tracking.ts`
- [Gamification](https://github.com/sanych44474/trix/blob/main/src/features/gamification/challenges.ts): `src/features/gamification/challenges.ts`

### Runtime services

- [Worker runtime](https://github.com/sanych44474/trix/blob/main/src/index.ts): `src/index.ts`
- [AI provider chain](https://github.com/sanych44474/trix/blob/main/src/ai/index.ts): `src/ai/index.ts`
- [Scheduled coaching](https://github.com/sanych44474/trix/blob/main/src/scheduler.ts): `src/scheduler.ts`

### Persistence

- **D1 database**
- [User records](https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Users.ts): `src/adapters/d1/v2Users.ts`
- [Plan records](https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Plans.ts): `src/adapters/d1/v2Plans.ts`
- [Workout records](https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Workouts.ts): `src/adapters/d1/v2Workouts.ts`
- [Nutrition records](https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Nutrition.ts): `src/adapters/d1/v2Nutrition.ts`
- [Trainer records](https://github.com/sanych44474/trix/blob/main/src/adapters/d1/v2Trainer.ts): `src/adapters/d1/v2Trainer.ts`

### Other components

- **Athlete**
- **Human trainer**

## Connections

- Athlete → Telegram chat: messages
- Athlete → Mini App: uses
- Human trainer → Telegram chat: manages clients
- Telegram chat → Worker runtime: webhook
- Mini App → Worker runtime: API requests
- Worker runtime → Bot routing: routes chat
- Bot routing → Onboarding: starts interview (evidence: `src/bot.ts`)
- Bot routing → Training plans: handles plans (evidence: `src/bot/router.ts`)
- Bot routing → AI provider chain: requests coaching (evidence: `src/bot.ts`)
- Bot routing → User records: loads user (evidence: `src/bot/router.ts`)
- Onboarding → User records: updates profile
- Training plans → Plan records: saves plan (evidence: `src/bot.ts`)
- Mini App → Workout logger: renders logger (evidence: `apps/mini-app/src/App.tsx`)
- Workout logger → Workout records: saves sessions
- Workout logger → Progression logic: supports progression
- Nutrition coaching → AI provider chain: parses meals (evidence: `src/features/nutrition/nutritionLog.ts`)
- Nutrition coaching → Nutrition records: stores food logs (evidence: `src/features/nutrition/nutritionLog.ts`)
- Body and recovery → D1 database: reads and writes
- Trainer tools → Trainer records: manages relationships (evidence: `src/features/trainer/trainer.ts`)
- Trainer tools → User records: updates clients (evidence: `src/features/trainer/trainer.ts`)
- Gamification → D1 database: records activity
- Worker runtime → Scheduled coaching: runs cron (evidence: `src/index.ts`)
- Scheduled coaching → D1 database: reads and writes
- User records → D1 database: persists accounts (evidence: `src/adapters/d1/v2Users.ts`)
- Plan records → D1 database: persists plans (evidence: `src/adapters/d1/v2Plans.ts`)
- Workout records → D1 database: persists workouts
- Nutrition records → D1 database: persists nutrition (evidence: `src/adapters/d1/v2Nutrition.ts`)
- Trainer records → D1 database: persists trainer data