# fresh-mc/tracker architecture

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

- Interactive diagram: https://gitdiagram.com/fresh-mc/tracker
- Repository: https://github.com/fresh-mc/tracker

## Overview

Tracker KPR is a team project-management platform. Users authenticate, enter protected dashboards, and work with teams, projects, and assigned tasks; the API persists application data and supports analytics, AI reports, GitHub integration, and team chat. Groups distinguish the React experience, Express API, domain operations, and persistence/integrations. Edges reflect excerpts, the SOURCE INDEX, or README statements; unsampled implementations are represented only where the documented capability and tree support them.

Main entry points: [`frontend/src/App.jsx`](https://github.com/fresh-mc/tracker/blob/main/frontend/src/App.jsx) (React application), [`server/src/server.js`](https://github.com/fresh-mc/tracker/blob/main/server/src/server.js) (API application), [`server/src/controllers/aiController.js`](https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/aiController.js) (AI and report operations), [`server/src/services/aiService.js`](https://github.com/fresh-mc/tracker/blob/main/server/src/services/aiService.js) (AI insights service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React application"]
  node_web["React application<br/>[App.jsx]"]
  node_authstate["Authentication state<br/>[AuthContext.jsx]"]
  node_login["Login and OAuth callback<br/>[AnimatedLogin.jsx]"]
  node_dashboard["Team dashboard<br/>[TeamDashboard.jsx]"]
  node_planning["Project planning<br/>[ProjectPlan.jsx]"]
  node_chatui["Team chat<br/>[Chat.jsx]"]
  node_analyticsui["Analytics dashboards"]
  node_projectanalytics["Project analytics"]
  node_teamanalytics["Team analytics<br/>[TeamAnalytics.jsx]"]
  node_aiui["AI insights<br/>[AIInsights.jsx]"]
  node_socketclient["Realtime socket client<br/>[useSocket.js]"]
end

subgraph group_api["Express API"]
  node_apiapp["API application<br/>[server.js]"]
  node_authroutes["Authentication routes<br/>[authRoutes.js]"]
  node_projectroutes["Project routes<br/>[projectRoutes.js]"]
  node_teamroutes["Team routes<br/>[teamRoutes.js]"]
  node_taskroutes["Task routes<br/>[taskRoutes.js]"]
  node_airoutes["AI and report routes<br/>[aiRoutes.js]"]
end

subgraph group_domain["Domain services"]
  node_authcontroller["Authentication operations<br/>[authController.js]"]
  node_projectcontroller["Project operations"]
  node_teamcontroller["Team operations<br/>[teamController.js]"]
  node_taskcontroller["Task operations<br/>[taskController.js]"]
  node_analyticscontroller["Analytics operations"]
  node_aicontroller["AI and report operations<br/>[aiController.js]"]
  node_aiservice["AI insights service<br/>[aiService.js]"]
  node_reportservice["Report generation<br/>[reportService.js]"]
end

subgraph group_data["Persistence and integrations"]
  node_models[("Project and team records<br/>[Project.js]")]
  node_taskmodel[("Task records<br/>[Task.js]")]
  node_usermodel[("User records<br/>[User.js]")]
  node_reportcache[("Report cache<br/>[ReportCache.js]")]
  node_mongodb[("MongoDB")]
  node_gemini["Google Gemini"]
  node_github["GitHub"]
  node_chatservice["Socket.IO chat service"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"routes to"| node_login
node_web -->|"routes to"| node_dashboard
node_web -->|"routes to"| node_planning
node_web -->|"routes to"| node_chatui
node_web -->|"routes to"| node_analyticsui
node_web -->|"routes to"| node_projectanalytics
node_web -->|"routes to"| node_teamanalytics
node_web -->|"routes to"| node_aiui
node_login -->|"uses"| node_authstate
node_authstate -.->|"authenticates through"| node_authroutes
node_web -->|"uses REST API"| node_apiapp
node_apiapp -->|"mounts"| node_authroutes
node_apiapp -->|"mounts"| node_projectroutes
node_apiapp -->|"mounts"| node_teamroutes
node_apiapp -->|"mounts"| node_taskroutes
node_apiapp -->|"mounts"| node_airoutes
node_authroutes -.->|"dispatches"| node_authcontroller
node_projectroutes -->|"dispatches"| node_projectcontroller
node_teamroutes -->|"dispatches"| node_teamcontroller
node_taskroutes -.->|"dispatches"| node_taskcontroller
node_airoutes -->|"dispatches"| node_aicontroller
node_projectcontroller -->|"reads and writes"| node_models
node_teamcontroller -->|"reads and writes"| node_models
node_teamcontroller -->|"updates members"| node_usermodel
node_taskcontroller -.->|"reads and writes"| node_taskmodel
node_analyticscontroller -.->|"analyzes"| node_models
node_aicontroller -->|"requests insights"| node_aiservice
node_aicontroller -->|"generates reports"| node_reportservice
node_aicontroller -->|"caches reports"| node_reportcache
node_aiservice -->|"generates content"| node_gemini
node_aiservice -->|"reads user data"| node_usermodel
node_aiservice -->|"reads projects"| node_models
node_apiapp -->|"connects to"| node_mongodb
node_web -->|"connects for chat"| node_chatservice
node_socketclient -->|"delivers live updates"| node_user
node_web -.->|"syncs GitHub data"| node_github

click node_web "https://github.com/fresh-mc/tracker/blob/main/frontend/src/App.jsx"
click node_authstate "https://github.com/fresh-mc/tracker/blob/main/frontend/src/context/AuthContext.jsx"
click node_login "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/AnimatedLogin.jsx"
click node_dashboard "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/TeamDashboard.jsx"
click node_planning "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/ProjectPlan.jsx"
click node_chatui "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/Chat.jsx"
click node_analyticsui "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/AnalyticsDashboard.jsx"
click node_projectanalytics "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/ProjectAnalytics.jsx"
click node_teamanalytics "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/TeamAnalytics.jsx"
click node_aiui "https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/AIInsights.jsx"
click node_socketclient "https://github.com/fresh-mc/tracker/blob/main/frontend/src/hooks/useSocket.js"
click node_apiapp "https://github.com/fresh-mc/tracker/blob/main/server/src/server.js"
click node_authroutes "https://github.com/fresh-mc/tracker/blob/main/server/src/routes/authRoutes.js"
click node_projectroutes "https://github.com/fresh-mc/tracker/blob/main/server/src/routes/projectRoutes.js"
click node_teamroutes "https://github.com/fresh-mc/tracker/blob/main/server/src/routes/teamRoutes.js"
click node_taskroutes "https://github.com/fresh-mc/tracker/blob/main/server/src/routes/taskRoutes.js"
click node_airoutes "https://github.com/fresh-mc/tracker/blob/main/server/src/routes/aiRoutes.js"
click node_authcontroller "https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/authController.js"
click node_projectcontroller "https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/projectController.js"
click node_teamcontroller "https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/teamController.js"
click node_taskcontroller "https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/taskController.js"
click node_analyticscontroller "https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/analyticsController.js"
click node_aicontroller "https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/aiController.js"
click node_aiservice "https://github.com/fresh-mc/tracker/blob/main/server/src/services/aiService.js"
click node_reportservice "https://github.com/fresh-mc/tracker/blob/main/server/src/services/reportService.js"
click node_models "https://github.com/fresh-mc/tracker/blob/main/server/src/models/Project.js"
click node_taskmodel "https://github.com/fresh-mc/tracker/blob/main/server/src/models/Task.js"
click node_usermodel "https://github.com/fresh-mc/tracker/blob/main/server/src/models/User.js"
click node_reportcache "https://github.com/fresh-mc/tracker/blob/main/server/src/models/ReportCache.js"

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_web,node_authstate,node_login,node_dashboard,node_planning,node_chatui,node_analyticsui,node_projectanalytics,node_teamanalytics,node_aiui,node_socketclient,node_user toneBlue
class node_apiapp,node_authroutes,node_projectroutes,node_teamroutes,node_taskroutes,node_airoutes toneAmber
class node_authcontroller,node_projectcontroller,node_teamcontroller,node_taskcontroller,node_analyticscontroller,node_aicontroller,node_aiservice,node_reportservice toneMint
class node_models,node_taskmodel,node_usermodel,node_reportcache,node_mongodb,node_gemini,node_github,node_chatservice toneRose
```

## Components

### React application

- [React application](https://github.com/fresh-mc/tracker/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Authentication state](https://github.com/fresh-mc/tracker/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Login and OAuth callback](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/AnimatedLogin.jsx): `frontend/src/pages/AnimatedLogin.jsx`
- [Team dashboard](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/TeamDashboard.jsx): `frontend/src/pages/TeamDashboard.jsx`
- [Project planning](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/ProjectPlan.jsx): `frontend/src/pages/ProjectPlan.jsx`
- [Team chat](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/Chat.jsx): `frontend/src/pages/Chat.jsx`
- [Analytics dashboards](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/AnalyticsDashboard.jsx): `frontend/src/pages/AnalyticsDashboard.jsx`
- [Project analytics](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/ProjectAnalytics.jsx): `frontend/src/pages/ProjectAnalytics.jsx`
- [Team analytics](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/TeamAnalytics.jsx): `frontend/src/pages/TeamAnalytics.jsx`
- [AI insights](https://github.com/fresh-mc/tracker/blob/main/frontend/src/pages/AIInsights.jsx): `frontend/src/pages/AIInsights.jsx`
- [Realtime socket client](https://github.com/fresh-mc/tracker/blob/main/frontend/src/hooks/useSocket.js): `frontend/src/hooks/useSocket.js`

### Express API

- [API application](https://github.com/fresh-mc/tracker/blob/main/server/src/server.js): `server/src/server.js`
- [Authentication routes](https://github.com/fresh-mc/tracker/blob/main/server/src/routes/authRoutes.js): `server/src/routes/authRoutes.js`
- [Project routes](https://github.com/fresh-mc/tracker/blob/main/server/src/routes/projectRoutes.js): `server/src/routes/projectRoutes.js`
- [Team routes](https://github.com/fresh-mc/tracker/blob/main/server/src/routes/teamRoutes.js): `server/src/routes/teamRoutes.js`
- [Task routes](https://github.com/fresh-mc/tracker/blob/main/server/src/routes/taskRoutes.js): `server/src/routes/taskRoutes.js`
- [AI and report routes](https://github.com/fresh-mc/tracker/blob/main/server/src/routes/aiRoutes.js): `server/src/routes/aiRoutes.js`

### Domain services

- [Authentication operations](https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/authController.js): `server/src/controllers/authController.js`
- [Project operations](https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/projectController.js): `server/src/controllers/projectController.js`
- [Team operations](https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/teamController.js): `server/src/controllers/teamController.js`
- [Task operations](https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/taskController.js): `server/src/controllers/taskController.js`
- [Analytics operations](https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/analyticsController.js): `server/src/controllers/analyticsController.js`
- [AI and report operations](https://github.com/fresh-mc/tracker/blob/main/server/src/controllers/aiController.js): `server/src/controllers/aiController.js`
- [AI insights service](https://github.com/fresh-mc/tracker/blob/main/server/src/services/aiService.js): `server/src/services/aiService.js`
- [Report generation](https://github.com/fresh-mc/tracker/blob/main/server/src/services/reportService.js): `server/src/services/reportService.js`

### Persistence and integrations

- [Project and team records](https://github.com/fresh-mc/tracker/blob/main/server/src/models/Project.js): `server/src/models/Project.js`
- [Task records](https://github.com/fresh-mc/tracker/blob/main/server/src/models/Task.js): `server/src/models/Task.js`
- [User records](https://github.com/fresh-mc/tracker/blob/main/server/src/models/User.js): `server/src/models/User.js`
- [Report cache](https://github.com/fresh-mc/tracker/blob/main/server/src/models/ReportCache.js): `server/src/models/ReportCache.js`
- **MongoDB**
- **Google Gemini**
- **GitHub**
- **Socket.IO chat service**

### Other components

- **User**

## Connections

- User → React application: uses (evidence: `README.md`)
- React application → Login and OAuth callback: routes to (evidence: `frontend/src/App.jsx`)
- React application → Team dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React application → Project planning: routes to (evidence: `frontend/src/App.jsx`)
- React application → Team chat: routes to (evidence: `frontend/src/App.jsx`)
- React application → Analytics dashboards: routes to (evidence: `frontend/src/App.jsx`)
- React application → Project analytics: routes to (evidence: `frontend/src/App.jsx`)
- React application → Team analytics: routes to (evidence: `frontend/src/App.jsx`)
- React application → AI insights: routes to (evidence: `frontend/src/App.jsx`)
- Login and OAuth callback → Authentication state: uses (evidence: `frontend/src/pages/AnimatedLogin.jsx`)
- Authentication state → Authentication routes: authenticates through
- React application → API application: uses REST API (evidence: `README.md`)
- API application → Authentication routes: mounts (evidence: `server/src/server.js`)
- API application → Project routes: mounts (evidence: `server/src/server.js`)
- API application → Team routes: mounts (evidence: `server/src/server.js`)
- API application → Task routes: mounts (evidence: `server/src/server.js`)
- API application → AI and report routes: mounts (evidence: `server/src/server.js`)
- Authentication routes → Authentication operations: dispatches
- Project routes → Project operations: dispatches (evidence: `server/src/routes/projectRoutes.js`)
- Team routes → Team operations: dispatches (evidence: `server/src/routes/teamRoutes.js`)
- Task routes → Task operations: dispatches
- AI and report routes → AI and report operations: dispatches (evidence: `server/src/routes/aiRoutes.js`)
- Project operations → Project and team records: reads and writes (evidence: `server/src/controllers/projectController.js`)
- Team operations → Project and team records: reads and writes (evidence: `server/src/controllers/teamController.js`)
- Team operations → User records: updates members (evidence: `server/src/controllers/teamController.js`)
- Task operations → Task records: reads and writes
- Analytics operations → Project and team records: analyzes
- AI and report operations → AI insights service: requests insights (evidence: `server/src/controllers/aiController.js`)
- AI and report operations → Report generation: generates reports (evidence: `server/src/controllers/aiController.js`)
- AI and report operations → Report cache: caches reports (evidence: `server/src/controllers/aiController.js`)
- AI insights service → Google Gemini: generates content (evidence: `server/src/services/aiService.js`)
- AI insights service → User records: reads user data (evidence: `server/src/services/aiService.js`)
- AI insights service → Project and team records: reads projects (evidence: `server/src/services/aiService.js`)
- API application → MongoDB: connects to (evidence: `server/src/server.js`)
- React application → Socket.IO chat service: connects for chat (evidence: `README.md`)
- Realtime socket client → User: delivers live updates (evidence: `frontend/src/hooks/useSocket.js`)
- React application → GitHub: syncs GitHub data
