Introduction & Key Features¶

Table of Contents¶

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

Introduction¶

Nexo is a video discovery and organization application that automates the processing of video content through an AI-powered pipeline, intelligent decision management, and media server integration. It transforms manual video organization into an automated workflow with intelligent decision-making: files are scanned, metadata is extracted, AI models classify content, confidence scores guide decisions, and approved outcomes sync to your media server. The system provides real-time monitoring, notifications, multi-language support, and user authentication for secure collaboration.

Key value proposition: - Replace tedious manual tagging and sorting with an automated pipeline that learns from your preferences. - Reduce errors and inconsistencies by applying consistent classification rules backed by AI and confidence scoring. - Keep your media library up-to-date automatically via media server integration.

Project Structure¶

The project follows a modular architecture with clear separation between service (backend), dashboard (frontend), shared models/schemas, and database migrations.

graph TB
subgraph "Service (FastAPI)"
SMain["apps/service/main.py"]
SApp["apps/service/app.py"]
Routes["apps/service/routes/*"]
Core["apps/service/core/*"]
Monitor["apps/service/monitor/watchdog.py"]
end
subgraph "Dashboard (React/Vite)"
DHome["apps/dashboard/src/pages/Home.tsx"]
DDecidir["apps/dashboard/src/pages/Decidir.tsx"]
DMedia["apps/dashboard/src/pages/MediaServer.tsx"]
DLogin["apps/dashboard/src/pages/Login.tsx"]
DLogs["apps/dashboard/src/pages/Logs.tsx"]
DConfig["apps/dashboard/src/pages/Config.tsx"]
DI18N["apps/dashboard/src/i18n/*.ts"]
end
subgraph "Shared"
SharedModels["apps/shared/models/*"]
SharedSchemas["apps/shared/schemas/*"]
SharedCfg["apps/shared/config.py"]
SharedDB["apps/shared/db.py"]
end
subgraph "Database"
Alembic["alembic/versions/*"]
end
SMain --> SApp
SApp --> Routes
Routes --> Core
Routes --> SharedModels
Routes --> SharedSchemas
Core --> SharedCfg
Core --> SharedDB
Monitor --> Core
DHome --> SApp
DDecidir --> SApp
DMedia --> SApp
DLogin --> SApp
DLogs --> SApp
DConfig --> SApp
DI18N --> DHome
DI18N --> DDecidir
DI18N --> DMedia
DI18N --> DLogin
DI18N --> DLogs
DI18N --> DConfig
SharedDB --> Alembic

Section sources - apps/service/main.py - apps/service/app.py - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/confidence.py - apps/service/core/decision.py - apps/service/routes/decisions.py - apps/service/routes/jellyfin.py - apps/service/routes/auth.py - apps/service/routes/status.py - apps/service/routes/logs.py - apps/service/routes/config.py - apps/service/routes/history.py - apps/service/routes/push.py - apps/service/monitor/watchdog.py - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/MediaServer.tsx - apps/dashboard/src/pages/Login.tsx - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/i18n/en-US.ts - apps/dashboard/src/i18n/pt-BR.ts - apps/shared/models/decision.py - apps/shared/schemas/decision.py - apps/shared/config.py - apps/shared/db.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py

Core Components¶

Pipeline orchestration: Coordinates scanning, parsing, classification, confidence evaluation, and decision creation.
Scanning and monitoring: Watches directories for new or changed videos and triggers the pipeline.
Decision management: Stores and exposes decisions with type, rationale, and confidence score; supports approval workflows.
Media server integration: Syncs approved decisions to Jellyfin to keep libraries organized.
Authentication and users: Secures access and manages user roles.
Real-time status and logs: Provides live updates and detailed logs for transparency.
Multi-language support: Localizes UI strings for different languages.

Practical examples: - Scan video files: Use the scan endpoint to process a directory; the pipeline extracts metadata and runs classification. - Review AI-generated decisions: Open the Decidir page to inspect suggested classifications and confidence scores. - Approve/reject classifications: Confirm or override decisions; approved items propagate to the media server. - Sync with media servers: Configure Jellyfin settings and trigger synchronization from the Media Server page.

Section sources - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/confidence.py - apps/service/core/decision.py - apps/service/routes/decisions.py - apps/service/routes/jellyfin.py - apps/service/routes/auth.py - apps/service/routes/status.py - apps/service/routes/logs.py - apps/service/routes/config.py - apps/service/routes/history.py - apps/service/routes/push.py - apps/service/monitor/watchdog.py - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/MediaServer.tsx - apps/dashboard/src/pages/Login.tsx - apps/dashboard/src/i18n/en-US.ts - apps/dashboard/src/i18n/pt-BR.ts

Architecture Overview¶

High-level flow from file change to media server update:

sequenceDiagram
participant FS as "File System"
participant Watchdog as "Monitor Watchdog"
participant Service as "Service App"
participant Pipeline as "Pipeline"
participant Scanner as "Scanner"
participant Classifier as "AI Classifier"
participant Confidence as "Confidence Scorer"
participant Decisions as "Decisions API"
participant DB as "Database"
participant Jellyfin as "Jellyfin Integration"
participant Dashboard as "Dashboard UI"
FS-->>Watchdog : "New/changed video detected"
Watchdog->>Service : "Trigger scan"
Service->>Pipeline : "Start pipeline"
Pipeline->>Scanner : "Scan and extract metadata"
Scanner-->>Pipeline : "Metadata"
Pipeline->>Classifier : "Classify content"
Classifier-->>Pipeline : "Labels + raw signals"
Pipeline->>Confidence : "Compute confidence score"
Confidence-->>Pipeline : "Score"
Pipeline->>Decisions : "Create decision"
Decisions->>DB : "Persist decision"
Dashboard->>Service : "Fetch decisions and status"
User->>Dashboard : "Approve/Reject decision"
Dashboard->>Service : "Submit decision action"
Service->>Jellyfin : "Sync approved items"
Jellyfin-->>Service : "Sync result"
Service-->>Dashboard : "Real-time updates"

Diagram sources - apps/service/monitor/watchdog.py - apps/service/app.py - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/confidence.py - apps/service/routes/decisions.py - apps/service/routes/jellyfin.py - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/MediaServer.tsx

Detailed Component Analysis¶

Pipeline Orchestration¶

The pipeline coordinates scanning, parsing, classification, confidence scoring, and decision creation. It ensures each stage can be monitored and retried independently.

flowchart TD
Start(["Start Pipeline"]) --> Scan["Scan and Extract Metadata"]
Scan --> Parse["Parse Content Signals"]
Parse --> Classify["AI Classification"]
Classify --> Score["Compute Confidence Score"]
Score --> Decide["Create Decision"]
Decide --> Persist["Persist to Database"]
Persist --> Notify["Notify Status/UI"]
Notify --> End(["Pipeline Complete"])

Diagram sources - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/confidence.py - apps/service/core/decision.py

Section sources - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/confidence.py - apps/service/core/decision.py

Decision Management¶

Decisions represent the outcome of classification with associated confidence scores and types. Users can review, approve, or reject them.

classDiagram
class Decision {
+id
+type
+confidence_score
+status
+metadata
+created_at
+updated_at
}
class DecisionSchema {
+validate()
+serialize()
}
class DecisionsRoutes {
+list_decisions()
+get_decision()
+approve_decision()
+reject_decision()
}
Decision <.. DecisionSchema : "validated by"
DecisionsRoutes --> Decision : "creates/updates"

Diagram sources - apps/shared/models/decision.py - apps/shared/schemas/decision.py - apps/service/routes/decisions.py

Section sources - apps/shared/models/decision.py - apps/shared/schemas/decision.py - apps/service/routes/decisions.py

Media Server Integration¶

Approved decisions synchronize with Jellyfin to keep your media library organized. Configuration and sync operations are exposed via dedicated routes.

sequenceDiagram
participant UI as "Media Server Page"
participant Config as "Config API"
participant Jellyfin as "Jellyfin API"
participant Decisions as "Decisions API"
participant DB as "Database"
UI->>Config : "Save Jellyfin settings"
Config->>DB : "Persist configuration"
UI->>Decisions : "List pending approvals"
Decisions->>DB : "Query decisions"
UI->>Jellyfin : "Sync approved items"
Jellyfin-->>UI : "Sync results"

Diagram sources - apps/service/routes/jellyfin.py - apps/service/routes/config.py - apps/service/routes/decisions.py - apps/dashboard/src/pages/MediaServer.tsx

Section sources - apps/service/routes/jellyfin.py - apps/service/routes/config.py - apps/service/routes/decisions.py - apps/dashboard/src/pages/MediaServer.tsx

Real-Time Monitoring and Notifications¶

Status and logs endpoints provide live insights into pipeline progress and events. Push subscriptions enable external notifications.

sequenceDiagram
participant Dashboard as "Dashboard UI"
participant Status as "Status API"
participant Logs as "Logs API"
participant Push as "Push API"
Dashboard->>Status : "Subscribe to status updates"
Status-->>Dashboard : "Streamed status events"
Dashboard->>Logs : "Fetch recent logs"
Logs-->>Dashboard : "Log entries"
Dashboard->>Push : "Register subscription"
Push-->>Dashboard : "Confirmation"

Diagram sources - apps/service/routes/status.py - apps/service/routes/logs.py - apps/service/routes/push.py - apps/dashboard/src/pages/Logs.tsx

Section sources - apps/service/routes/status.py - apps/service/routes/logs.py - apps/service/routes/push.py - apps/dashboard/src/pages/Logs.tsx

User Authentication¶

Authentication routes protect sensitive endpoints and manage user sessions.

sequenceDiagram
participant Login as "Login Page"
participant Auth as "Auth API"
participant Dashboard as "Dashboard UI"
Login->>Auth : "Authenticate credentials"
Auth-->>Login : "Session/token"
Login->>Dashboard : "Navigate to protected pages"

Diagram sources - apps/service/routes/auth.py - apps/dashboard/src/pages/Login.tsx

Section sources - apps/service/routes/auth.py - apps/dashboard/src/pages/Login.tsx

Multi-Language Support¶

The dashboard uses i18n modules to localize UI text across supported languages.

graph LR
EN["en-US.ts"] --> Home["Home.tsx"]
PT["pt-BR.ts"] --> Home
EN --> Decidir["Decidir.tsx"]
PT --> Decidir
EN --> Media["MediaServer.tsx"]
PT --> Media
EN --> Login["Login.tsx"]
PT --> Login
EN --> Logs["Logs.tsx"]
PT --> Logs
EN --> Config["Config.tsx"]
PT --> Config

Diagram sources - apps/dashboard/src/i18n/en-US.ts - apps/dashboard/src/i18n/pt-BR.ts - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/MediaServer.tsx - apps/dashboard/src/pages/Login.tsx - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/Config.tsx

Section sources - apps/dashboard/src/i18n/en-US.ts - apps/dashboard/src/i18n/pt-BR.ts - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/MediaServer.tsx - apps/dashboard/src/pages/Login.tsx - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/Config.tsx

Dependency Analysis¶

The service layer depends on shared models and schemas for data contracts, while the dashboard consumes REST APIs and localizations.

graph TB
Routes["routes/*"] --> Models["shared/models/*"]
Routes --> Schemas["shared/schemas/*"]
Routes --> Core["core/*"]
Core --> Config["shared/config.py"]
Core --> DB["shared/db.py"]
DB --> Alembic["alembic/versions/*"]
Dashboard["dashboard/src/pages/*"] --> Routes
Dashboard --> I18N["dashboard/src/i18n/*"]

Performance Considerations¶

Batch scanning: Group file scans to reduce overhead when processing large directories.
Asynchronous pipeline stages: Run classification and IO-bound tasks concurrently where possible.
Caching: Cache repeated metadata extraction and classification results to speed up reprocessing.
Incremental sync: Only sync changes to the media server to minimize network calls.
Rate limiting: Respect media server API limits to avoid throttling.

Troubleshooting Guide¶

Common issues and checks: - Pipeline stalls: Inspect logs and status endpoints to identify failed stages. - Low confidence scores: Review classification inputs and adjust thresholds if needed. - Jellyfin sync failures: Verify configuration and connectivity; check sync results and error messages. - Authentication problems: Ensure credentials are correct and session tokens are valid. - Language display issues: Confirm selected locale and availability of translation files.

Section sources - apps/service/routes/logs.py - apps/service/routes/status.py - apps/service/routes/jellyfin.py - apps/service/routes/auth.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/MediaServer.tsx - apps/dashboard/src/pages/Login.tsx

Conclusion¶

Nexo streamlines video organization by combining automated scanning, AI-driven classification with confidence scoring, and robust decision management. With media server integration, real-time monitoring, multi-language support, and user authentication, it delivers a complete, scalable solution for turning manual effort into an intelligent, repeatable workflow.