shreyash-03-codes/sportiq

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