# miteshpanda/tacticsensei architecture

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

- Interactive diagram: https://gitdiagram.com/miteshpanda/tacticsensei
- Repository: https://github.com/miteshpanda/tacticsensei

## Overview

TacticSensei is a football-learning platform for beginners. Its main user journey is exploring structured Academy lessons and reference material, with quizzes and an AI tutor as interactive learning paths; the encyclopedias, comparison tool, and World Cup predictor extend that experience. The backend exposes these capabilities through FastAPI routes, with profile services, authentication, and persistent content and user data behind them. The README documents the product capabilities; source excerpts and the index support backend routing and selected service/storage links. Frontend-to-backend wiring is not shown, so those links are omitted.

Main entry points: [`backend/app/api/router.py`](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/router.py) (API router), [`backend/app/api/endpoints/academy.py`](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/academy.py) (Lesson content), [`backend/app/api/endpoints/quiz.py`](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/quiz.py) (Lesson quizzes), [`backend/app/api/endpoints/glossary.py`](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/glossary.py) (Glossary routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learn["Football Academy"]
  node_academy_ui["Academy lessons<br/>[page.tsx]"]
  node_academy_content["Lesson content<br/>[academy.py]"]
  node_lesson_quiz["Lesson quizzes<br/>[quiz.py]"]
  node_curriculum_data["Curriculum data<br/>[curriculum.ts]"]
end

subgraph group_reference["Football Reference"]
  node_profiles_ui["Player profiles<br/>[page.tsx]"]
  node_teams_ui["Team profiles<br/>[page.tsx]"]
  node_coaches_ui["Coach profiles<br/>[page.tsx]"]
  node_glossary_ui["Football glossary<br/>[page.tsx]"]
  node_profile_routes["Profile routes<br/>[players.py]"]
  node_teams_routes["Team routes<br/>[teams.py]"]
  node_coaches_routes["Coach routes<br/>[coaches.py]"]
  node_glossary_routes["Glossary routes<br/>[glossary.py]"]
  node_profile_service["Profile service<br/>[profiles.py]"]
end

subgraph group_interactive["Interactive Tools"]
  node_tutor_ui["AI football tutor<br/>[page.tsx]"]
  node_tutor_route["Tutor route<br/>[tutor.py]"]
  node_tutor_service["Tutor service<br/>[tutor.py]"]
  node_predictor_ui["World Cup predictor<br/>[page.tsx]"]
  node_predictor_route["Predictor route<br/>[predictor.py]"]
  node_compare_ui["Compare tool<br/>[page.tsx]"]
end

subgraph group_identity["Identity And Admin"]
  node_auth_ui["Sign in<br/>[page.tsx]"]
  node_auth_context["Auth context<br/>[AuthContext.tsx]"]
  node_admin_ui["Admin dashboard<br/>[page.tsx]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_auth_middleware["JWT authentication<br/>[auth.py]"]
  node_users_routes["User routes<br/>[users.py]"]
  node_users_repo["User repository<br/>[users_repo.py]"]
  node_favorites_routes["Favorites routes<br/>[favorites.py]"]
  node_favorites_repo["Favorites repository<br/>[favorites_repo.py]"]
end

subgraph group_backend["API And Data"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_sql_db[("SQL database<br/>[database.py]")]
  node_orm_models["Content models<br/>[models.py]"]
  node_supabase_client["Supabase client<br/>[supabase_client.py]"]
end

node_learner(("Football learner"))

node_learner -->|"studies"| node_academy_ui
node_learner -->|"explores"| node_profiles_ui
node_learner -->|"explores"| node_teams_ui
node_learner -->|"explores"| node_coaches_ui
node_learner -->|"looks up"| node_glossary_ui
node_learner -->|"asks questions"| node_tutor_ui
node_learner -->|"simulates"| node_predictor_ui
node_learner -->|"compares"| node_compare_ui
node_api_app -->|"mounts routes"| node_api_router
node_api_router -->|"registers"| node_academy_content
node_api_router -->|"registers"| node_lesson_quiz
node_api_router -->|"registers"| node_profile_routes
node_api_router -->|"registers"| node_teams_routes
node_api_router -->|"registers"| node_coaches_routes
node_api_router -->|"registers"| node_glossary_routes
node_api_router -->|"registers"| node_tutor_route
node_api_router -->|"registers"| node_predictor_route
node_api_router -->|"registers"| node_users_routes
node_api_router -->|"registers"| node_favorites_routes
node_api_router -->|"registers"| node_admin_routes
node_academy_content -->|"queries"| node_sql_db
node_academy_content -->|"uses models"| node_orm_models
node_lesson_quiz -->|"queries"| node_sql_db
node_lesson_quiz -->|"uses models"| node_orm_models
node_glossary_routes -->|"queries"| node_sql_db
node_glossary_routes -->|"uses models"| node_orm_models
node_profile_routes -->|"delegates"| node_profile_service
node_teams_routes -->|"delegates"| node_profile_service
node_coaches_routes -->|"delegates"| node_profile_service
node_tutor_route -->|"delegates"| node_tutor_service
node_users_routes -->|"delegates"| node_users_repo
node_users_repo -->|"gets client"| node_supabase_client
node_favorites_routes -->|"requires user"| node_auth_middleware
node_favorites_routes -->|"delegates"| node_favorites_repo
node_admin_routes -->|"checks access"| node_auth_middleware
node_admin_routes -->|"reads and writes"| node_supabase_client

click node_academy_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/academy/page.tsx"
click node_academy_content "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/academy.py"
click node_lesson_quiz "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/quiz.py"
click node_curriculum_data "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/data/academy/curriculum.ts"
click node_profiles_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/players/%5Bslug%5D/page.tsx"
click node_teams_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/teams/%5Bslug%5D/page.tsx"
click node_coaches_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/coaches/%5Bslug%5D/page.tsx"
click node_glossary_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/glossary/page.tsx"
click node_profile_routes "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/players.py"
click node_teams_routes "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/teams.py"
click node_coaches_routes "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/coaches.py"
click node_glossary_routes "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/glossary.py"
click node_profile_service "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/services/profiles.py"
click node_tutor_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/tutor/page.tsx"
click node_tutor_route "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/tutor.py"
click node_tutor_service "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/services/tutor.py"
click node_predictor_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/predictor/page.tsx"
click node_predictor_route "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/predictor.py"
click node_compare_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/compare/page.tsx"
click node_auth_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/auth/page.tsx"
click node_auth_context "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/context/AuthContext.tsx"
click node_admin_ui "https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/admin/%5Bsection%5D/page.tsx"
click node_admin_routes "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/admin.py"
click node_auth_middleware "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/middleware/auth.py"
click node_users_routes "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/users.py"
click node_users_repo "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/repositories/users_repo.py"
click node_api_app "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/main.py"
click node_api_router "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/router.py"
click node_sql_db "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/core/database.py"
click node_orm_models "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/models/models.py"
click node_supabase_client "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/core/supabase_client.py"
click node_favorites_routes "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/favorites.py"
click node_favorites_repo "https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/repositories/favorites_repo.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_academy_ui,node_academy_content,node_lesson_quiz,node_curriculum_data toneBlue
class node_profiles_ui,node_teams_ui,node_coaches_ui,node_glossary_ui,node_profile_routes,node_teams_routes,node_coaches_routes,node_glossary_routes,node_profile_service toneAmber
class node_tutor_ui,node_tutor_route,node_tutor_service,node_predictor_ui,node_predictor_route,node_compare_ui toneMint
class node_auth_ui,node_auth_context,node_admin_ui,node_admin_routes,node_auth_middleware,node_users_routes,node_users_repo,node_favorites_routes,node_favorites_repo toneRose
class node_api_app,node_api_router,node_sql_db,node_orm_models,node_supabase_client,node_learner toneIndigo
```

## Components

### Football Academy

- [Academy lessons](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/academy/page.tsx): `frontend/src/app/academy/page.tsx`
- [Lesson content](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/academy.py): `backend/app/api/endpoints/academy.py`
- [Lesson quizzes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/quiz.py): `backend/app/api/endpoints/quiz.py`
- [Curriculum data](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/data/academy/curriculum.ts): `frontend/src/data/academy/curriculum.ts`

### Football Reference

- [Player profiles](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/players/%5Bslug%5D/page.tsx): `frontend/src/app/players/[slug]/page.tsx`
- [Team profiles](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/teams/%5Bslug%5D/page.tsx): `frontend/src/app/teams/[slug]/page.tsx`
- [Coach profiles](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/coaches/%5Bslug%5D/page.tsx): `frontend/src/app/coaches/[slug]/page.tsx`
- [Football glossary](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/glossary/page.tsx): `frontend/src/app/glossary/page.tsx`
- [Profile routes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/players.py): `backend/app/api/endpoints/players.py`
- [Team routes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/teams.py): `backend/app/api/endpoints/teams.py`
- [Coach routes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/coaches.py): `backend/app/api/endpoints/coaches.py`
- [Glossary routes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/glossary.py): `backend/app/api/endpoints/glossary.py`
- [Profile service](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/services/profiles.py): `backend/app/services/profiles.py`

### Interactive Tools

- [AI football tutor](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/tutor/page.tsx): `frontend/src/app/tutor/page.tsx`
- [Tutor route](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/tutor.py): `backend/app/api/endpoints/tutor.py`
- [Tutor service](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/services/tutor.py): `backend/app/services/tutor.py`
- [World Cup predictor](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/predictor/page.tsx): `frontend/src/app/predictor/page.tsx`
- [Predictor route](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/predictor.py): `backend/app/api/endpoints/predictor.py`
- [Compare tool](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/compare/page.tsx): `frontend/src/app/compare/page.tsx`

### Identity And Admin

- [Sign in](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/auth/page.tsx): `frontend/src/app/auth/page.tsx`
- [Auth context](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Admin dashboard](https://github.com/miteshpanda/tacticsensei/blob/main/frontend/src/app/admin/%5Bsection%5D/page.tsx): `frontend/src/app/admin/[section]/page.tsx`
- [Admin routes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/admin.py): `backend/app/api/endpoints/admin.py`
- [JWT authentication](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/middleware/auth.py): `backend/app/middleware/auth.py`
- [User routes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/users.py): `backend/app/api/endpoints/users.py`
- [User repository](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/repositories/users_repo.py): `backend/app/repositories/users_repo.py`
- [Favorites routes](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/endpoints/favorites.py): `backend/app/api/endpoints/favorites.py`
- [Favorites repository](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/repositories/favorites_repo.py): `backend/app/repositories/favorites_repo.py`

### API And Data

- [FastAPI application](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [SQL database](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Content models](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/models/models.py): `backend/app/models/models.py`
- [Supabase client](https://github.com/miteshpanda/tacticsensei/blob/main/backend/app/core/supabase_client.py): `backend/app/core/supabase_client.py`

### Other components

- **Football learner**

## Connections

- Football learner → Academy lessons: studies
- Football learner → Player profiles: explores
- Football learner → Team profiles: explores
- Football learner → Coach profiles: explores
- Football learner → Football glossary: looks up
- Football learner → AI football tutor: asks questions
- Football learner → World Cup predictor: simulates
- Football learner → Compare tool: compares
- FastAPI application → API router: mounts routes (evidence: `backend/app/main.py`)
- API router → Lesson content: registers (evidence: `backend/app/api/router.py`)
- API router → Lesson quizzes: registers (evidence: `backend/app/api/router.py`)
- API router → Profile routes: registers (evidence: `backend/app/api/router.py`)
- API router → Team routes: registers (evidence: `backend/app/api/router.py`)
- API router → Coach routes: registers (evidence: `backend/app/api/router.py`)
- API router → Glossary routes: registers (evidence: `backend/app/api/router.py`)
- API router → Tutor route: registers (evidence: `backend/app/api/router.py`)
- API router → Predictor route: registers (evidence: `backend/app/api/router.py`)
- API router → User routes: registers (evidence: `backend/app/api/router.py`)
- API router → Favorites routes: registers (evidence: `backend/app/api/router.py`)
- API router → Admin routes: registers (evidence: `backend/app/api/router.py`)
- Lesson content → SQL database: queries (evidence: `backend/app/api/endpoints/academy.py`)
- Lesson content → Content models: uses models (evidence: `backend/app/api/endpoints/academy.py`)
- Lesson quizzes → SQL database: queries (evidence: `backend/app/api/endpoints/quiz.py`)
- Lesson quizzes → Content models: uses models (evidence: `backend/app/api/endpoints/quiz.py`)
- Glossary routes → SQL database: queries (evidence: `backend/app/api/endpoints/glossary.py`)
- Glossary routes → Content models: uses models (evidence: `backend/app/api/endpoints/glossary.py`)
- Profile routes → Profile service: delegates (evidence: `backend/app/api/endpoints/players.py`)
- Team routes → Profile service: delegates (evidence: `backend/app/api/endpoints/teams.py`)
- Coach routes → Profile service: delegates (evidence: `backend/app/api/endpoints/coaches.py`)
- Tutor route → Tutor service: delegates (evidence: `backend/app/api/endpoints/tutor.py`)
- User routes → User repository: delegates (evidence: `backend/app/api/endpoints/users.py`)
- User repository → Supabase client: gets client (evidence: `backend/app/repositories/users_repo.py`)
- Favorites routes → JWT authentication: requires user (evidence: `backend/app/api/endpoints/favorites.py`)
- Favorites routes → Favorites repository: delegates (evidence: `backend/app/api/endpoints/favorites.py`)
- Admin routes → JWT authentication: checks access (evidence: `backend/app/api/endpoints/admin.py`)
- Admin routes → Supabase client: reads and writes (evidence: `backend/app/api/endpoints/admin.py`)
