# isharak7m/forge architecture

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

- Interactive diagram: https://gitdiagram.com/isharak7m/forge
- Repository: https://github.com/isharak7m/forge

## Overview

Forge is an AI fitness platform: users log workouts, meals, sleep, water, and weight, then review dashboards, trends, predictions, and recommendations. The React app routes authenticated users to feature pages and calls a Spring REST API; backend services process domain data and persist it through repositories. Documented AI capabilities include weight and workout predictions, plateau detection, adherence scoring, and recommendations. Source excerpts are selective, so links to unsampled domain implementations are shown only where documented or marked unverified.

Main entry points: [`src/main/java/com/forge/repository`](https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/repository) (Data repositories), [`src/main/java/com/forge/service/DashboardService.java`](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/DashboardService.java) (Dashboard aggregation), [`frontend/src/api`](https://github.com/isharak7m/forge/tree/master/frontend/src/api) (API clients), [`src/main/java/com/forge/service/AuthService.java`](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/AuthService.java) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_pages["Feature pages"]
  node_webapi["API clients"]
  node_authstate["Auth state<br/>[authStore.ts]"]
end

subgraph group_api["API and identity"]
  node_authcontroller["Auth endpoints"]
  node_authservice["Authentication<br/>[AuthService.java]"]
  node_security["JWT security"]
  node_usercontroller["Profile endpoints"]
end

subgraph group_tracking["Fitness tracking"]
  node_domaincontrollers["Tracking endpoints"]
  node_nutrition["Nutrition logging"]
  node_workouts["Workout tracking"]
  node_wellness["Sleep water weight"]
  node_dashboardcontroller["Dashboard endpoint"]
  node_dashboard["Dashboard aggregation"]
end

subgraph group_insights["AI and insights"]
  node_aicontroller["AI endpoints<br/>[AIController.java]"]
  node_ml["Prediction and scoring"]
  node_recommendations["Recommendations"]
  node_aitools["AI tool execution"]
end

subgraph group_persistence["Domain data"]
  node_userentity["User profile model<br/>[User.java]"]
  node_repositories["Data repositories"]
end

node_person(("Fitness user"))
node_postgres[("PostgreSQL")]

node_person -->|"uses"| node_app
node_app -->|"routes to"| node_pages
node_app -->|"checks session"| node_authstate
node_pages -.->|"requests data"| node_webapi
node_webapi -.->|"calls API"| node_authcontroller
node_webapi -.->|"calls API"| node_domaincontrollers
node_webapi -.->|"calls API"| node_aicontroller
node_authcontroller -.->|"delegates to"| node_authservice
node_authservice -->|"reads and saves"| node_repositories
node_authservice -->|"creates token"| node_security
node_authservice -->|"creates user"| node_userentity
node_usercontroller -.->|"serves profile"| node_userentity
node_domaincontrollers -->|"delegates nutrition"| node_nutrition
node_domaincontrollers -.->|"delegates workouts"| node_workouts
node_domaincontrollers -.->|"delegates logs"| node_wellness
node_nutrition -->|"reads and writes"| node_repositories
node_workouts -->|"reads and writes"| node_repositories
node_dashboardcontroller -.->|"delegates to"| node_dashboard
node_dashboard -->|"aggregates nutrition"| node_nutrition
node_dashboard -->|"aggregates workouts"| node_workouts
node_dashboard -->|"aggregates logs"| node_wellness
node_dashboard -->|"reads summaries"| node_repositories
node_aicontroller -->|"invokes models"| node_ml
node_aicontroller -->|"requests recommendations"| node_recommendations
node_aicontroller -->|"dispatches tools"| node_aitools
node_ml -.->|"reads history"| node_repositories
node_recommendations -->|"uses scores"| node_ml
node_recommendations -.->|"reads activity"| node_repositories
node_repositories -.->|"persists records"| node_postgres

click node_app "https://github.com/isharak7m/forge/blob/master/frontend/src/App.tsx"
click node_pages "https://github.com/isharak7m/forge/tree/master/frontend/src/pages"
click node_webapi "https://github.com/isharak7m/forge/tree/master/frontend/src/api"
click node_authstate "https://github.com/isharak7m/forge/blob/master/frontend/src/store/authStore.ts"
click node_authcontroller "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/AuthController.java"
click node_authservice "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/AuthService.java"
click node_security "https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/security"
click node_usercontroller "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/UserController.java"
click node_domaincontrollers "https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/controller"
click node_nutrition "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/NutritionService.java"
click node_workouts "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/WorkoutService.java"
click node_wellness "https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/service"
click node_dashboardcontroller "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/AnalyticsDashboardController.java"
click node_dashboard "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/DashboardService.java"
click node_aicontroller "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/AIController.java"
click node_ml "https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/ai/ml"
click node_recommendations "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/ai/recommendation/RecommendationService.java"
click node_aitools "https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/ai/tool"
click node_userentity "https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/entity/User.java"
click node_repositories "https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/repository"

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_app,node_pages,node_webapi,node_authstate,node_person toneBlue
class node_authcontroller,node_authservice,node_security,node_usercontroller,node_postgres toneAmber
class node_domaincontrollers,node_nutrition,node_workouts,node_wellness,node_dashboardcontroller,node_dashboard toneMint
class node_aicontroller,node_ml,node_recommendations,node_aitools toneRose
class node_userentity,node_repositories toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/isharak7m/forge/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Feature pages](https://github.com/isharak7m/forge/tree/master/frontend/src/pages): `frontend/src/pages`
- [API clients](https://github.com/isharak7m/forge/tree/master/frontend/src/api): `frontend/src/api`
- [Auth state](https://github.com/isharak7m/forge/blob/master/frontend/src/store/authStore.ts): `frontend/src/store/authStore.ts`

### API and identity

- [Auth endpoints](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/AuthController.java): `src/main/java/com/forge/controller/AuthController.java`
- [Authentication](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/AuthService.java): `src/main/java/com/forge/service/AuthService.java`
- [JWT security](https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/security): `src/main/java/com/forge/security`
- [Profile endpoints](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/UserController.java): `src/main/java/com/forge/controller/UserController.java`

### Fitness tracking

- [Tracking endpoints](https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/controller): `src/main/java/com/forge/controller`
- [Nutrition logging](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/NutritionService.java): `src/main/java/com/forge/service/NutritionService.java`
- [Workout tracking](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/WorkoutService.java): `src/main/java/com/forge/service/WorkoutService.java`
- [Sleep water weight](https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/service): `src/main/java/com/forge/service`
- [Dashboard endpoint](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/AnalyticsDashboardController.java): `src/main/java/com/forge/controller/AnalyticsDashboardController.java`
- [Dashboard aggregation](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/service/DashboardService.java): `src/main/java/com/forge/service/DashboardService.java`

### AI and insights

- [AI endpoints](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/controller/AIController.java): `src/main/java/com/forge/controller/AIController.java`
- [Prediction and scoring](https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/ai/ml): `src/main/java/com/forge/ai/ml`
- [Recommendations](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/ai/recommendation/RecommendationService.java): `src/main/java/com/forge/ai/recommendation/RecommendationService.java`
- [AI tool execution](https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/ai/tool): `src/main/java/com/forge/ai/tool`

### Domain data

- [User profile model](https://github.com/isharak7m/forge/blob/master/src/main/java/com/forge/entity/User.java): `src/main/java/com/forge/entity/User.java`
- [Data repositories](https://github.com/isharak7m/forge/tree/master/src/main/java/com/forge/repository): `src/main/java/com/forge/repository`

### Other components

- **Fitness user**
- **PostgreSQL**

## Connections

- Fitness user → App routing: uses (evidence: `README.md`)
- App routing → Feature pages: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Auth state: checks session (evidence: `frontend/src/App.tsx`)
- Feature pages → API clients: requests data (evidence: `frontend/src/pages/WorkoutsPage.tsx`)
- API clients → Auth endpoints: calls API
- API clients → Tracking endpoints: calls API
- API clients → AI endpoints: calls API
- Auth endpoints → Authentication: delegates to
- Authentication → Data repositories: reads and saves (evidence: `src/main/java/com/forge/service/AuthService.java`)
- Authentication → JWT security: creates token (evidence: `src/main/java/com/forge/service/AuthService.java`)
- Authentication → User profile model: creates user (evidence: `src/main/java/com/forge/service/AuthService.java`)
- Profile endpoints → User profile model: serves profile
- Tracking endpoints → Nutrition logging: delegates nutrition (evidence: `src/main/java/com/forge/controller/NutritionController.java`)
- Tracking endpoints → Workout tracking: delegates workouts (evidence: `src/main/java/com/forge/controller/WorkoutController.java`)
- Tracking endpoints → Sleep water weight: delegates logs (evidence: `src/main/java/com/forge/controller/NutritionController.java`)
- Nutrition logging → Data repositories: reads and writes (evidence: `src/main/java/com/forge/service/NutritionService.java`)
- Workout tracking → Data repositories: reads and writes (evidence: `src/main/java/com/forge/service/WorkoutService.java`)
- Dashboard endpoint → Dashboard aggregation: delegates to
- Dashboard aggregation → Nutrition logging: aggregates nutrition (evidence: `src/main/java/com/forge/service/DashboardService.java`)
- Dashboard aggregation → Workout tracking: aggregates workouts (evidence: `src/main/java/com/forge/service/DashboardService.java`)
- Dashboard aggregation → Sleep water weight: aggregates logs (evidence: `src/main/java/com/forge/service/DashboardService.java`)
- Dashboard aggregation → Data repositories: reads summaries (evidence: `src/main/java/com/forge/service/DashboardService.java`)
- AI endpoints → Prediction and scoring: invokes models (evidence: `src/main/java/com/forge/controller/AIController.java`)
- AI endpoints → Recommendations: requests recommendations (evidence: `src/main/java/com/forge/controller/AIController.java`)
- AI endpoints → AI tool execution: dispatches tools (evidence: `src/main/java/com/forge/controller/AIController.java`)
- Prediction and scoring → Data repositories: reads history (evidence: `src/main/java/com/forge/ai/ml/WorkoutPredictionService.java`)
- Recommendations → Prediction and scoring: uses scores (evidence: `src/main/java/com/forge/ai/recommendation/RecommendationService.java`)
- Recommendations → Data repositories: reads activity (evidence: `src/main/java/com/forge/ai/recommendation/RecommendationService.java`)
- Data repositories → PostgreSQL: persists records
