# bhuwanenthiran/athletedna-ai architecture

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

- Interactive diagram: https://gitdiagram.com/bhuwanenthiran/athletedna-ai
- Repository: https://github.com/bhuwanenthiran/athletedna-ai

## Overview

#### Purpose and Runtime
AthleteDNA AI is a React/TypeScript sports-coaching prototype: athletes complete movement assessments, receive a seven-trait biomechanical profile, compare against a generic matched profile, and consume personalized training, nutrition, and recovery guidance. It is a Vite client application with an optional server bootstrap. Core entry/runtime paths: `src/start.ts`, `src/server.ts`, `vite.config.ts`.

#### Application Composition and Navigation
Routing is centralized through the router and generated route tree, with a root layout providing shared application framing. The main product journey spans onboarding, assessment, results, scan comparison, and plan; returning and staff workflows use dashboard, coach chat, and team views.
- `src/router.tsx`
- `src/routeTree.gen.ts`
- `src/routes/__root.tsx`
- `src/components/AppShell.tsx`

#### Athlete Assessment and Profile Flow
The athlete-facing flow begins by capturing sport, role, and goals, proceeds through webcam/pose-assessment UI, then presents scored profile results. These screens currently consume typed local data rather than a backend, preserving a replacement boundary for real capture, pose-analysis, and scoring services.
- `src/routes/onboarding.tsx`
- `src/routes/assessment.tsx`
- `src/routes/results.tsx`
- `src/data/types.ts`
- `src/data/mocks.ts`

#### Biomechanical Visualization Stage
The scan comparison route is the visual centerpiece: it composes a controlled 3D hologram scene with two simplified pose/skeleton figures, then overlays animated match and trait-comparison UI. Three.js runs through react-three-fiber/drei; motion sequencing is expected through Framer Motion. The scene is isolated from general route UI to constrain graphics complexity and support mobile-specific layout behavior.
- `src/routes/scan-comparison.tsx`
- `src/components/scan/ScanScene.tsx`
- `src/components/scan/HologramFigure.tsx`

#### Recommendation and Engagement Surfaces
After comparison, the plan route turns the matched-profile and trait data into training/nutrition/recovery guidance. Dashboard exposes longitudinal trends, streaks, and reassessment prompts. Coach chat is the future integration point for an AI coaching service, while team supports a coach-facing multi-athlete comparison workflow.
- `src/routes/plan.tsx`
- `src/routes/dashboard.tsx`
- `src/routes/coach-chat.tsx`
- `src/routes/team.tsx`

#### Shared Presentation, State, and Localization
The UI is a dark biometric-lab design built from shared components, theme/mobile hooks, and translation resources. `useTranslation` and locale JSONs form the localization boundary. The generated UI component library under `src/components/ui` supplies primitives but is not the product domain layer.
- `src/styles.css`
- `src/hooks/useTheme.tsx`
- `src/hooks/useTranslation.tsx`
- `src/locales/en.json`

#### Offline and Client Resilience
The app includes progressive-web-app behavior: service-worker assets, an offline fallback, install/banner handling, and a client-side persistence/error boundary layer. Browser storage/database behavior is encapsulated rather than distributed through routes.
- `public/sw.js`
- `public/offline.html`
- `src/hooks/usePWA.tsx`
- `src/lib/db.ts`
- `src/lib/error-capture.ts`

#### External Boundaries
Current domain values are local mocks; no backend, authentication provider, webcam SDK, pose-tracking API, or AI model integration is represented in the tree. Planned external boundaries are therefore: browser media capture and pose analysis feeding assessment results; an AI/backend service producing profile matching and plans; and potentially durable athlete/team storage. Lovable is the project synchronization/deployment environment, not an in-app runtime dependency.

Main entry points: [`src/router.tsx`](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/router.tsx) (Router & route tree), [`src/routes/assessment.tsx`](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/assessment.tsx) (Assessment), [`src/routes/results.tsx`](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/results.tsx) (Profile results), [`src/routes/scan-comparison.tsx`](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/scan-comparison.tsx) (Scan comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_vite{{"Vite bootstrap<br/>client runtime<br/>[vite.config.ts]"}}
  node_start["Client entry<br/>entrypoint<br/>[start.ts]"]
  node_server["Optional server<br/>server bootstrap<br/>[server.ts]"]
  node_router["Router &amp; route tree<br/>navigation<br/>[router.tsx]"]
  node_root["Root layout<br/>shared layout<br/>[__root.tsx]"]
  node_shell["App shell<br/>presentation shell<br/>[AppShell.tsx]"]
end

subgraph group_journey["Athlete journey"]
  node_onboarding["Onboarding<br/>athlete route<br/>[onboarding.tsx]"]
  node_assessment["Assessment<br/>athlete route<br/>[assessment.tsx]"]
  node_results["Profile results<br/>athlete route<br/>[results.tsx]"]
  node_domain_data[("Typed local profile data<br/>local data boundary<br/>[mocks.ts]")]
end

subgraph group_visualization["3D comparison"]
  node_scan_route["Scan comparison<br/>athlete route"]
  node_scan_scene["Hologram scene<br/>3D scene<br/>[ScanScene.tsx]"]
  node_hologram["Pose figures<br/>3D figure<br/>[HologramFigure.tsx]"]
end

subgraph group_engagement["Guidance &amp; staff"]
  node_plan["Personalized plan<br/>athlete route<br/>[plan.tsx]"]
  node_dashboard["Athlete dashboard<br/>athlete route<br/>[dashboard.tsx]"]
  node_coach_chat["Coach chat<br/>future AI surface<br/>[coach-chat.tsx]"]
  node_team["Team view<br/>coach route<br/>[team.tsx]"]
end

subgraph group_platform["Client platform"]
  node_client_platform["Theme, locale &amp; resilience<br/>client platform<br/>[usePWA.tsx]"]
  node_offline["Offline fallback<br/>PWA asset<br/>[offline.html]"]
end

node_browser_capture(("Browser capture &amp; pose analysis<br/>planned external boundary"))
node_ai_backend(("AI/backend services<br/>planned external boundary"))
node_durable_storage[("Athlete/team storage<br/>planned external boundary")]

node_vite -->|"serves"| node_start
node_vite -.->|"can bootstrap"| node_server
node_start -->|"initializes"| node_router
node_router -->|"renders under"| node_root
node_root -->|"frames with"| node_shell
node_router -->|"routes to"| node_onboarding
node_router -->|"routes to"| node_assessment
node_router -->|"routes to"| node_results
node_router -->|"routes to"| node_scan_route
node_router -->|"routes to"| node_plan
node_router -->|"routes to"| node_dashboard
node_router -->|"routes to"| node_coach_chat
node_router -->|"routes to"| node_team
node_onboarding -->|"continues to"| node_assessment
node_assessment -->|"produces profile"| node_results
node_domain_data -->|"supplies local values"| node_assessment
node_domain_data -->|"supplies traits"| node_results
node_results -->|"compares profile"| node_scan_route
node_scan_route -->|"composes"| node_scan_scene
node_scan_scene -->|"renders two"| node_hologram
node_scan_route -->|"feeds guidance"| node_plan
node_domain_data -->|"supplies traits and match"| node_plan
node_client_platform -->|"provides fallback"| node_offline
node_assessment -.->|"future input"| node_browser_capture
node_browser_capture -.->|"future analysis"| node_ai_backend
node_ai_backend -.->|"future scoring"| node_results
node_ai_backend -.->|"future recommendations"| node_plan
node_ai_backend -.->|"future coaching"| node_coach_chat
node_ai_backend -.->|"may persist"| node_durable_storage
node_dashboard -.->|"future history"| node_durable_storage
node_team -.->|"future roster data"| node_durable_storage

click node_vite "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/vite.config.ts"
click node_start "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/start.ts"
click node_server "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/server.ts"
click node_router "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/router.tsx"
click node_root "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/__root.tsx"
click node_shell "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/components/AppShell.tsx"
click node_onboarding "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/onboarding.tsx"
click node_assessment "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/assessment.tsx"
click node_results "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/results.tsx"
click node_domain_data "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/data/mocks.ts"
click node_scan_route "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/scan-comparison.tsx"
click node_scan_scene "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/components/scan/ScanScene.tsx"
click node_hologram "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/components/scan/HologramFigure.tsx"
click node_plan "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/plan.tsx"
click node_dashboard "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/dashboard.tsx"
click node_coach_chat "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/coach-chat.tsx"
click node_team "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/team.tsx"
click node_client_platform "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/hooks/usePWA.tsx"
click node_offline "https://github.com/bhuwanenthiran/athletedna-ai/blob/main/public/offline.html"

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_vite,node_start,node_server,node_router,node_root,node_shell toneBlue
class node_onboarding,node_assessment,node_results,node_domain_data toneAmber
class node_scan_route,node_scan_scene,node_hologram toneMint
class node_plan,node_dashboard,node_coach_chat,node_team toneRose
class node_client_platform,node_offline toneIndigo
class node_browser_capture,node_ai_backend,node_durable_storage toneNeutral
```

## Components

### Runtime

- [Vite bootstrap](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/vite.config.ts): client runtime · Vite client runtime with optional server bootstrap. · `vite.config.ts`
- [Client entry](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/start.ts): entrypoint · `src/start.ts`
- [Optional server](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/server.ts): server bootstrap · `src/server.ts`
- [Router & route tree](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/router.tsx): navigation · Centralized routing for product and staff workflows. · `src/router.tsx`
- [Root layout](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/__root.tsx): shared layout · `src/routes/__root.tsx`
- [App shell](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/components/AppShell.tsx): presentation shell · `src/components/AppShell.tsx`

### Athlete journey

- [Onboarding](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/onboarding.tsx): athlete route · Captures sport, role, and goals. · `src/routes/onboarding.tsx`
- [Assessment](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/assessment.tsx): athlete route · Webcam and pose-assessment UI replacement boundary. · `src/routes/assessment.tsx`
- [Profile results](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/results.tsx): athlete route · Presents the seven-trait biomechanical profile. · `src/routes/results.tsx`
- [Typed local profile data](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/data/mocks.ts): local data boundary · Mocks stand in for capture, analysis, and scoring services. · `src/data/mocks.ts`

### 3D comparison

- [Scan comparison](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/scan-comparison.tsx): athlete route · Compares athlete and generic matched profiles. · `src/routes/scan-comparison.tsx`
- [Hologram scene](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/components/scan/ScanScene.tsx): 3D scene · Isolated react-three-fiber scene with mobile-aware layout. · `src/components/scan/ScanScene.tsx`
- [Pose figures](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/components/scan/HologramFigure.tsx): 3D figure · Simplified skeleton figures for comparison. · `src/components/scan/HologramFigure.tsx`

### Guidance & staff

- [Personalized plan](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/plan.tsx): athlete route · Turns traits and match data into training, nutrition, and recovery guidance. · `src/routes/plan.tsx`
- [Athlete dashboard](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/dashboard.tsx): athlete route · Shows trends, streaks, and reassessment prompts. · `src/routes/dashboard.tsx`
- [Coach chat](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/coach-chat.tsx): future AI surface · Integration point for an AI coaching service. · `src/routes/coach-chat.tsx`
- [Team view](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/routes/team.tsx): coach route · Coach-facing multi-athlete comparison workflow. · `src/routes/team.tsx`

### Client platform

- [Theme, locale & resilience](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/src/hooks/usePWA.tsx): client platform · Shared styling, localization, PWA behavior, storage, and error capture. · `src/hooks/usePWA.tsx`
- [Offline fallback](https://github.com/bhuwanenthiran/athletedna-ai/blob/main/public/offline.html): PWA asset · `public/offline.html`

### Other components

- **Browser capture & pose analysis**: planned external boundary · Future media capture and pose-analysis input.
- **AI/backend services**: planned external boundary · Future profile matching and plan generation.
- **Athlete/team storage**: planned external boundary · Potential durable domain persistence.

## Connections

- Vite bootstrap → Client entry: serves
- Vite bootstrap → Optional server: can bootstrap
- Client entry → Router & route tree: initializes
- Router & route tree → Root layout: renders under
- Root layout → App shell: frames with
- Router & route tree → Onboarding: routes to
- Router & route tree → Assessment: routes to
- Router & route tree → Profile results: routes to
- Router & route tree → Scan comparison: routes to
- Router & route tree → Personalized plan: routes to
- Router & route tree → Athlete dashboard: routes to
- Router & route tree → Coach chat: routes to
- Router & route tree → Team view: routes to
- Onboarding → Assessment: continues to
- Assessment → Profile results: produces profile
- Typed local profile data → Assessment: supplies local values
- Typed local profile data → Profile results: supplies traits
- Profile results → Scan comparison: compares profile
- Scan comparison → Hologram scene: composes
- Hologram scene → Pose figures: renders two
- Scan comparison → Personalized plan: feeds guidance
- Typed local profile data → Personalized plan: supplies traits and match
- Theme, locale & resilience → Offline fallback: provides fallback
- Assessment → Browser capture & pose analysis: future input
- Browser capture & pose analysis → AI/backend services: future analysis
- AI/backend services → Profile results: future scoring
- AI/backend services → Personalized plan: future recommendations
- AI/backend services → Coach chat: future coaching
- AI/backend services → Athlete/team storage: may persist
- Athlete dashboard → Athlete/team storage: future history
- Team view → Athlete/team storage: future roster data