# shreyash-03-codes/sportiq architecture

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

- Interactive diagram: https://gitdiagram.com/shreyash-03-codes/sportiq
- Repository: https://github.com/shreyash-03-codes/sportiq

## Overview

#### Purpose and deployment shape
SportIQ is a full-stack application for authenticated users to submit sports-skill videos, receive AI analysis and scores, and view saved analysis history. It consists of an Angular SPA, a Spring Boot API, PostgreSQL persistence, FFmpeg-based video processing, and an Ollama-backed Spring AI integration. Container orchestration is defined in `docker-compose.yml`; service images are built from `backend/Dockerfile` and `frontend/Dockerfile`.

#### Entry points and API boundary
The backend starts at `backend/src/main/java/com/sportiq/backend/BackendApplication.java`. HTTP endpoints are organized by responsibility: authentication, user/profile, sport/skill discovery, and analysis submission/history:
- `backend/src/main/java/com/sportiq/backend/web/AuthController.java`
- `backend/src/main/java/com/sportiq/backend/web/AnalysisController.java`
- `backend/src/main/java/com/sportiq/backend/web/SportController.java`

Controllers accept/return web DTOs and delegate business work to services; `GlobalExceptionHandler` converts domain, validation, media, and LLM failures to API errors.

#### Frontend application
The Angular application bootstraps from `frontend/src/main.ts`, with route and provider composition in `frontend/src/app/app.routes.ts` and `frontend/src/app/app.config.ts`. Major user workflows are login/registration, analysis upload, history, and profile:
- `frontend/src/app/analyze/analyze.component.ts`
- `frontend/src/app/history/history.component.ts`
- `frontend/src/app/core/analysis.service.ts`

Core services call the backend. An authentication interceptor attaches tokens, while route guards separate authenticated and guest-only routes (`frontend/src/app/core/auth.interceptor.ts`, `frontend/src/app/core/auth.guard.ts`).

#### Identity and authorization
JWT security is enforced at the backend boundary. `SecurityConfig` configures protected access; `JwtAuthenticationFilter` extracts and validates bearer tokens; `JwtService` creates and verifies tokens. `AuthService` owns registration/login behavior and persists users through `AppUserRepository`.
- `backend/src/main/java/com/sportiq/backend/security/SecurityConfig.java`
- `backend/src/main/java/com/sportiq/backend/security/JwtAuthenticationFilter.java`
- `backend/src/main/java/com/sportiq/backend/service/AuthService.java`

#### Analysis pipeline
`AnalysisService` is the orchestration point for a submitted video. The expected flow is: validate uploaded video → extract frames via FFmpeg/process execution → construct skill-specific AI prompt → invoke Ollama → validate structured AI output → persist a session and associated score(s) → return an analysis response. Media files are temporary operational artifacts and are cleaned up by the media layer.
- `backend/src/main/java/com/sportiq/backend/service/AnalysisService.java`
- `backend/src/main/java/com/sportiq/backend/media/VideoValidationService.java`
- `backend/src/main/java/com/sportiq/backend/media/FrameExtractionService.java`
- `backend/src/main/java/com/sportiq/backend/ai/SpringAiOllamaService.java`
- `backend/src/main/java/com/sportiq/backend/ai/AnalysisValidator.java`

#### AI and media infrastructure boundaries
The AI adapter is isolated in `ai`: `PromptService` selects/builds prompts using `SkillPrompt`; `SpringAiOllamaService` calls the external Ollama model runtime; `AnalysisResult` is the internal result contract. FFmpeg is an external host/container executable invoked through `ProcessRunner`, with properties separating executable/media configuration from business logic.
- `backend/src/main/java/com/sportiq/backend/ai/AiConfig.java`
- `backend/src/main/java/com/sportiq/backend/media/ProcessRunner.java`
- `backend/src/main/java/com/sportiq/backend/media/FfmpegProperties.java`

#### Domain persistence and history
JPA entities model users, sport/skill taxonomy, analysis sessions, and scores. `SportSkillService` supplies available sports/skills; `HistoryService` retrieves user-scoped sessions; `AnalysisService` creates durable results. Repository interfaces form the persistence boundary, backed by PostgreSQL in deployment and integration testing.
- `backend/src/main/java/com/sportiq/backend/entity/AnalysisSession.java`
- `backend/src/main/java/com/sportiq/backend/entity/AnalysisScore.java`
- `backend/src/main/java/com/sportiq/backend/service/HistoryService.java`
- `backend/src/main/java/com/sportiq/backend/repository/AnalysisSessionRepository.java`

#### Configuration and initialization
Spring configuration resides in `backend/src/main/resources/application.yml`, with container-specific overrides in `backend/src/main/resources/application-docker.yml`. `DataSeeder` initializes the sport/skill catalog, making taxonomy available to both analysis prompt selection and frontend selection flows.
- `backend/src/main/java/com/sportiq/backend/config/DataSeeder.java`
- `backend/src/main/resources/application.yml`

Main entry points: [`backend/src/main/java/com/sportiq/backend/web/AnalysisController.java`](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/web/AnalysisController.java) (HTTP controllers), [`backend/src/main/java/com/sportiq/backend/repository/AnalysisSessionRepository.java`](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/repository/AnalysisSessionRepository.java) (JPA repositories), [`docker-compose.yml`](https://github.com/shreyash-03-codes/sportiq/blob/main/docker-compose.yml) (Container orchestration), [`backend/src/main/java/com/sportiq/backend/service/AnalysisService.java`](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/service/AnalysisService.java) (Analysis orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Angular SPA"]
  node_spa["Angular application<br/>Angular SPA<br/>[main.ts]"]
  node_routes["Routes and providers<br/>Angular composition<br/>[app.routes.ts]"]
  node_analysis_ui["Analyze and history UI<br/>Angular workflows"]
  node_frontend_api["Analysis API client<br/>Angular service"]
  node_frontend_auth["Token interceptor and guards<br/>Angular auth"]
end

subgraph group_backend["Spring Boot API"]
  node_api["Spring Boot API<br/>application entry point"]
  node_controllers["HTTP controllers<br/>REST boundary"]
  node_security["JWT security<br/>security filter chain"]
  node_auth["Authentication service<br/>business service<br/>[AuthService.java]"]
  node_history["History and sport catalog<br/>query services"]
end

subgraph group_pipeline["Analysis pipeline"]
  node_analysis{{"Analysis orchestration<br/>business service"}}
  node_media["Video validation and frames<br/>media service"]
  node_ai["AI prompt and validation<br/>AI adapter layer"]
end

subgraph group_data["Persistence"]
  node_repositories["JPA repositories<br/>persistence boundary"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_seeder["Sport and skill seeder<br/>initialization<br/>[DataSeeder.java]"]
end

subgraph group_external["External runtimes"]
  node_ffmpeg["FFmpeg process<br/>host executable<br/>[ProcessRunner.java]"]
  node_ollama["Ollama runtime<br/>model runtime"]
  node_compose["Container orchestration<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_spa -->|"bootstraps"| node_routes
node_routes -->|"routes users"| node_analysis_ui
node_analysis_ui -->|"submits and reads analyses"| node_frontend_api
node_frontend_auth -->|"adds bearer token"| node_frontend_api
node_frontend_api -->|"HTTP API"| node_controllers
node_api -->|"hosts"| node_controllers
node_controllers -->|"protected requests"| node_security
node_controllers -->|"login and registration"| node_auth
node_controllers -->|"analysis submission"| node_analysis
node_controllers -->|"history and skills"| node_history
node_analysis -->|"validates and extracts frames"| node_media
node_media -->|"executes"| node_ffmpeg
node_analysis -->|"sends frames and skill context"| node_ai
node_ai -->|"model invocation"| node_ollama
node_analysis -->|"persists sessions and scores"| node_repositories
node_auth -->|"persists users"| node_repositories
node_history -->|"reads user data and taxonomy"| node_repositories
node_repositories -->|"JPA persistence"| node_postgres
node_seeder -->|"seeds taxonomy"| node_repositories
node_compose -.->|"runs backend image"| node_api
node_compose -.->|"runs frontend image"| node_spa
node_compose -.->|"runs database"| node_postgres
node_compose -.->|"runs model runtime"| node_ollama

click node_spa "https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/main.ts"
click node_routes "https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/app.routes.ts"
click node_analysis_ui "https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/analyze/analyze.component.ts"
click node_frontend_api "https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/core/analysis.service.ts"
click node_frontend_auth "https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/core/auth.interceptor.ts"
click node_api "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/BackendApplication.java"
click node_controllers "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/web/AnalysisController.java"
click node_security "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/security/SecurityConfig.java"
click node_auth "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/service/AuthService.java"
click node_analysis "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/service/AnalysisService.java"
click node_media "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/media/FrameExtractionService.java"
click node_ffmpeg "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/media/ProcessRunner.java"
click node_ai "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/ai/AnalysisValidator.java"
click node_ollama "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/ai/SpringAiOllamaService.java"
click node_history "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/service/HistoryService.java"
click node_repositories "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/repository/AnalysisSessionRepository.java"
click node_seeder "https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/config/DataSeeder.java"
click node_compose "https://github.com/shreyash-03-codes/sportiq/blob/main/docker-compose.yml"

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_spa,node_routes,node_analysis_ui,node_frontend_api,node_frontend_auth toneBlue
class node_api,node_controllers,node_security,node_auth,node_history toneAmber
class node_analysis,node_media,node_ai toneMint
class node_repositories,node_postgres,node_seeder toneRose
class node_ffmpeg,node_ollama,node_compose toneIndigo
```

## Components

### Angular SPA

- [Angular application](https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/main.ts): Angular SPA · Authenticated video analysis UI. · `frontend/src/main.ts`
- [Routes and providers](https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/app.routes.ts): Angular composition · `frontend/src/app/app.routes.ts`
- [Analyze and history UI](https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/analyze/analyze.component.ts): Angular workflows · `frontend/src/app/analyze/analyze.component.ts`
- [Analysis API client](https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/core/analysis.service.ts): Angular service · `frontend/src/app/core/analysis.service.ts`
- [Token interceptor and guards](https://github.com/shreyash-03-codes/sportiq/blob/main/frontend/src/app/core/auth.interceptor.ts): Angular auth · Attaches tokens and gates routes. · `frontend/src/app/core/auth.interceptor.ts`

### Spring Boot API

- [Spring Boot API](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/BackendApplication.java): application entry point · `backend/src/main/java/com/sportiq/backend/BackendApplication.java`
- [HTTP controllers](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/web/AnalysisController.java): REST boundary · Auth, analysis, and sport endpoints use web DTOs. · `backend/src/main/java/com/sportiq/backend/web/AnalysisController.java`
- [JWT security](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/security/SecurityConfig.java): security filter chain · Protects API requests and validates bearer tokens. · `backend/src/main/java/com/sportiq/backend/security/SecurityConfig.java`
- [Authentication service](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/service/AuthService.java): business service · Registers users and issues JWTs. · `backend/src/main/java/com/sportiq/backend/service/AuthService.java`
- [History and sport catalog](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/service/HistoryService.java): query services · Provides user-scoped history and available skills. · `backend/src/main/java/com/sportiq/backend/service/HistoryService.java`

### Analysis pipeline

- [Analysis orchestration](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/service/AnalysisService.java): business service · Coordinates media, AI, and durable results. · `backend/src/main/java/com/sportiq/backend/service/AnalysisService.java`
- [Video validation and frames](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/media/FrameExtractionService.java): media service · Validates uploads and cleans temporary media artifacts. · `backend/src/main/java/com/sportiq/backend/media/FrameExtractionService.java`
- [AI prompt and validation](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/ai/AnalysisValidator.java): AI adapter layer · Builds skill prompts and validates structured model output. · `backend/src/main/java/com/sportiq/backend/ai/AnalysisValidator.java`

### Persistence

- [JPA repositories](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/repository/AnalysisSessionRepository.java): persistence boundary · `backend/src/main/java/com/sportiq/backend/repository/AnalysisSessionRepository.java`
- **PostgreSQL**: relational database · Stores users, taxonomy, sessions, and scores.
- [Sport and skill seeder](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/config/DataSeeder.java): initialization · Initializes the taxonomy catalog. · `backend/src/main/java/com/sportiq/backend/config/DataSeeder.java`

### External runtimes

- [FFmpeg process](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/media/ProcessRunner.java): host executable · Invoked through ProcessRunner to extract frames. · `backend/src/main/java/com/sportiq/backend/media/ProcessRunner.java`
- [Ollama runtime](https://github.com/shreyash-03-codes/sportiq/blob/main/backend/src/main/java/com/sportiq/backend/ai/SpringAiOllamaService.java): model runtime · `backend/src/main/java/com/sportiq/backend/ai/SpringAiOllamaService.java`
- [Container orchestration](https://github.com/shreyash-03-codes/sportiq/blob/main/docker-compose.yml): Docker Compose · Runs application and infrastructure services. · `docker-compose.yml`

## Connections

- Angular application → Routes and providers: bootstraps
- Routes and providers → Analyze and history UI: routes users
- Analyze and history UI → Analysis API client: submits and reads analyses
- Token interceptor and guards → Analysis API client: adds bearer token
- Analysis API client → HTTP controllers: HTTP API
- Spring Boot API → HTTP controllers: hosts
- HTTP controllers → JWT security: protected requests
- HTTP controllers → Authentication service: login and registration
- HTTP controllers → Analysis orchestration: analysis submission
- HTTP controllers → History and sport catalog: history and skills
- Analysis orchestration → Video validation and frames: validates and extracts frames
- Video validation and frames → FFmpeg process: executes
- Analysis orchestration → AI prompt and validation: sends frames and skill context
- AI prompt and validation → Ollama runtime: model invocation
- Analysis orchestration → JPA repositories: persists sessions and scores
- Authentication service → JPA repositories: persists users
- History and sport catalog → JPA repositories: reads user data and taxonomy
- JPA repositories → PostgreSQL: JPA persistence
- Sport and skill seeder → JPA repositories: seeds taxonomy
- Container orchestration → Spring Boot API: runs backend image
- Container orchestration → Angular application: runs frontend image
- Container orchestration → PostgreSQL: runs database
- Container orchestration → Ollama runtime: runs model runtime