Development Guide¶

Table of Contents¶

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
Appendices

Introduction¶

This guide explains how to set up a local development environment, build and run both backend and frontend components, test the application, follow code style guidelines, and contribute via pull requests. It also covers debugging techniques for Python and React, continuous integration considerations, and deployment pipelines.

Project Structure¶

The repository is a multi-component project: - Backend service (FastAPI-based) under apps/service with shared models and schemas under apps/shared. - Frontend dashboard (React + Vite + TypeScript) under apps/dashboard. - Database migrations managed by Alembic. - Build scripts at the repository root for packaging and release.

graph TB
subgraph "Backend"
SMain["apps/service/main.py"]
SApp["apps/service/app.py"]
SDeps["apps/service/deps.py"]
SDB["apps/shared/db.py"]
SModels["apps/shared/models/*"]
SSchemas["apps/shared/schemas/*"]
SRoutes["apps/service/routes/*"]
SCores["apps/service/core/*"]
end
subgraph "Frontend"
FMain["apps/dashboard/src/main.tsx"]
FApp["apps/dashboard/src/App.tsx"]
FPages["apps/dashboard/src/pages/*"]
FComp["apps/dashboard/src/components/*"]
FHooks["apps/dashboard/src/hooks/*"]
FI18N["apps/dashboard/src/i18n/*"]
FConf["apps/dashboard/vite.config.ts"]
FPkg["apps/dashboard/package.json"]
end
subgraph "Database"
AEnv["alembic/env.py"]
AIni["alembic.ini"]
end
subgraph "Build & Entry"
BPy["build.py"]
BV2["build-v2.py"]
RPy["release.py"]
Ipy["index.py"]
end
FMain --> FApp
FApp --> FPages
FApp --> FComp
FApp --> FHooks
FApp --> FI18N
FApp --> FConf
FApp --> FPkg
SMain --> SApp
SApp --> SDeps
SDeps --> SDB
SApp --> SRoutes
SRoutes --> SCores
SRoutes --> SModels
SRoutes --> SSchemas
SDB --> AEnv
AEnv --> AIni
BPy --> SMain
BV2 --> SMain
RPy --> BPy
Ipy --> SMain

Diagram sources - apps/service/main.py - apps/service/app.py - apps/service/deps.py - apps/shared/db.py - alembic/env.py - alembic.ini - apps/dashboard/src/main.tsx - apps/dashboard/src/App.tsx - apps/dashboard/vite.config.ts - apps/dashboard/package.json - build.py - build-v2.py - release.py - index.py

Section sources - README.md - requirements.txt - setup.py - alembic.ini - alembic/env.py - apps/service/main.py - apps/service/app.py - apps/service/deps.py - apps/shared/db.py - apps/dashboard/package.json - apps/dashboard/vite.config.ts - apps/dashboard/tsconfig.json - build.py - build-v2.py - release.py - index.py

Core Components¶

Backend API server: FastAPI application entrypoint and dependency injection setup.
Shared layer: Pydantic schemas and SQLAlchemy models used across routes and core logic.
Core business modules: pipeline orchestration, matching, organization, scanning, and type definitions.
Routes: REST endpoints for authentication, configuration, decisions, history, Jellyfin integration, logs, push notifications, status, tools, and users.
Frontend dashboard: React app with Vite, TypeScript, i18n, hooks, and page components.
Database: Alembic-managed migrations and database connection configuration.
Build and release: Packaging scripts and top-level entry points.

Key responsibilities: - apps/service/main.py: Application startup and configuration. - apps/service/app.py: FastAPI app instance and middleware setup. - apps/service/deps.py: Dependency providers (e.g., DB sessions). - apps/shared/db.py: Database engine/session configuration. - alembic/env.py: Migration runner configuration. - apps/dashboard/src/main.tsx and App.tsx: Frontend bootstrap and routing. - vite.config.ts and package.json: Frontend build and dev server settings.

Section sources - apps/service/main.py - apps/service/app.py - apps/service/deps.py - apps/shared/db.py - alembic/env.py - apps/dashboard/src/main.tsx - apps/dashboard/src/App.tsx - apps/dashboard/vite.config.ts - apps/dashboard/package.json

Architecture Overview¶

High-level runtime architecture: - The frontend serves static assets and communicates with the backend over HTTP. - The backend exposes REST APIs and uses shared schemas/models for validation and persistence. - Database migrations are executed via Alembic. - Build scripts package the application for distribution.

sequenceDiagram
participant Dev as "Developer"
participant FE as "Dashboard (Vite)"
participant BE as "FastAPI Service"
participant DB as "Database"
participant AM as "Alembic"
Dev->>AM : "Run migrations"
AM->>DB : "Apply schema changes"
Dev->>FE : "Start dev server"
FE->>BE : "HTTP requests (REST)"
BE->>DB : "Query/Update via session"
BE-->>FE : "JSON responses"
FE-->>Dev : "UI updates"

Diagram sources - apps/service/main.py - apps/service/app.py - apps/shared/db.py - alembic/env.py - apps/dashboard/vite.config.ts - apps/dashboard/src/main.tsx

Detailed Component Analysis¶

Backend Service¶

Responsibilities: - Initialize FastAPI app and configure dependencies. - Register route modules. - Provide shared services (database sessions, config).

classDiagram
class ServiceMain {
+startup()
+shutdown()
}
class ServiceApp {
+app
+middleware()
}
class Deps {
+get_db_session()
}
class SharedDB {
+engine
+session_factory
}
class Routes {
+auth
+config
+decisions
+history
+jellyfin
+logs
+push
+status
+tools
+users
}
class Core {
+pipeline
+matcher
+organizer
+scan
+types
}
ServiceMain --> ServiceApp : "creates"
ServiceApp --> Deps : "uses"
Deps --> SharedDB : "configures"
ServiceApp --> Routes : "includes routers"
Routes --> Core : "calls"

Frontend Dashboard¶

Responsibilities: - Bootstrap React app and configure routing. - Provide UI components, pages, hooks, and internationalization. - Configure Vite for development and production builds.

flowchart TD
Start(["Frontend Startup"]) --> LoadConfig["Load Vite Config"]
LoadConfig --> InstallDeps["Install Dependencies"]
InstallDeps --> RunDev["Run Dev Server"]
RunDev --> RenderApp["Render App Root"]
RenderApp --> RoutePages["Route to Pages"]
RoutePages --> FetchAPI["Call Backend APIs"]
FetchAPI --> UpdateUI["Update UI State"]
UpdateUI --> End(["User Interaction"])

Diagram sources - apps/dashboard/vite.config.ts - apps/dashboard/package.json - apps/dashboard/src/main.tsx - apps/dashboard/src/App.tsx - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Login.tsx - apps/dashboard/src/components/Layout.tsx - apps/dashboard/src/hooks/usePush.ts - apps/dashboard/src/i18n/en-US.ts - apps/dashboard/src/i18n/pt-BR.ts

Section sources - apps/dashboard/package.json - apps/dashboard/vite.config.ts - apps/dashboard/tsconfig.json - apps/dashboard/src/main.tsx - apps/dashboard/src/App.tsx - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Login.tsx - apps/dashboard/src/components/Layout.tsx - apps/dashboard/src/hooks/usePush.ts - apps/dashboard/src/i18n/en-US.ts - apps/dashboard/src/i18n/pt-BR.ts

Database and Migrations¶

Alembini configuration and migration runner.
Database engine and session factory setup.
Models and schemas define data contracts.

flowchart TD
Init(["Init DB Layer"]) --> CreateEngine["Create Engine"]
CreateEngine --> SessionFactory["Configure Session Factory"]
SessionFactory --> RunMigrations["Run Alembic Migrations"]
RunMigrations --> Ready["DB Ready"]

Diagram sources - alembic/env.py - alembic.ini - apps/shared/db.py - apps/shared/models/init.py - apps/shared/schemas/init.py

Section sources - alembic/env.py - alembic.ini - apps/shared/db.py - apps/shared/models/init.py - apps/shared/schemas/init.py

Dependency Analysis¶

External and internal dependencies: - Python packages defined in requirements.txt and setup.py. - Node.js workspace for the dashboard with its own package.json. - Alembic for migrations.

graph LR
Req["requirements.txt"] --> PyPkg["Python Packages"]
Setup["setup.py"] --> PyPkg
Pkg["apps/dashboard/package.json"] --> NPM["Node Modules"]
Vite["apps/dashboard/vite.config.ts"] --> NPM
Alembi["alembic.ini"] --> Alembic["Alembic"]
Env["alembic/env.py"] --> Alembic

Diagram sources - requirements.txt - setup.py - apps/dashboard/package.json - apps/dashboard/vite.config.ts - alembic.ini - alembic/env.py

Section sources - requirements.txt - setup.py - apps/dashboard/package.json - apps/dashboard/vite.config.ts - alembic.ini - alembic/env.py

Performance Considerations¶

Use connection pooling for database sessions and avoid long-running transactions in request handlers.
Cache frequently accessed read-only data where appropriate.
Minimize payload sizes by selecting only necessary fields in queries.
For the frontend, leverage Vite’s optimized builds and lazy-load heavy components.
Profile hot paths in core modules (e.g., matcher, organizer) using standard Python profiling tools.

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Common issues and diagnostics: - Backend startup failures: verify environment variables, database connectivity, and Alembic migrations applied. - CORS or network errors between frontend and backend: ensure correct base URLs and ports in Vite config and browser dev tools. - Authentication problems: check route handlers and token handling. - Frontend build errors: inspect TypeScript and Vite configurations; clear node_modules if needed. - Logging: use backend logging to trace request flows and errors.

Section sources - apps/service/main.py - apps/service/app.py - apps/service/routes/auth.py - apps/dashboard/vite.config.ts - apps/dashboard/src/main.tsx

Conclusion¶

You now have a complete overview of the project structure, development workflow, testing strategy, code standards, contribution process, debugging techniques, CI considerations, and deployment pipelines. Follow the steps below to get started locally and contribute effectively.

[No sources needed since this section summarizes without analyzing specific files]

Appendices¶

Local Development Environment Setup¶

Python virtual environment:
Create and activate a virtual environment.
Install backend dependencies from requirements.txt.
Ensure Python version matches project constraints.
Node.js workspace:
Install Node.js compatible with the dashboard’s configuration.
Navigate to apps/dashboard and install dependencies using the provided package manager.
Database initialization:
Configure database URL in the shared database module.
Apply Alembic migrations before starting the backend.

Section sources - requirements.txt - setup.py - apps/dashboard/package.json - apps/shared/db.py - alembic/env.py - alembic.ini