System Design & Architecture Patterns¶

Table of Contents¶

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

Introduction¶

This document describes the system design and core architecture patterns of Nexo. It focuses on a modular, service-oriented architecture with clear separation between API services, core business logic, data management, and presentation layers. The system employs a microservices approach where a FastAPI-based service layer orchestrates a processing pipeline, interacts with database models, and integrates with external APIs. Key architectural patterns include event-driven processing, plugin-style parsers and classifiers, dependency injection, and centralized configuration and logging. Cross-cutting concerns such as error handling, security, and third-party dependency management are addressed throughout.

Project Structure¶

The repository is organized into distinct application areas: - Service layer (FastAPI): routes, core business logic, shared schemas and models, database access, and external integrations - Dashboard (React + Electron): web UI packaged for desktop distribution - Tray and Notify: background utilities for system integration and notifications - Shared modules: configuration, database setup, models, and schemas - Migrations: Alembic schema migrations - Legacy and utility scripts under src/ and root

graph TB
subgraph "Presentation"
D["Dashboard (Electron + React)"]
T["Tray App"]
N["Notify Service"]
end
subgraph "Service Layer"
SMain["FastAPI Main"]
Routes["Routes (Auth, Config, Decisions, History, Jellyfin, Logs, Push, Status, Tools, Users)"]
Core["Core Business Logic<br/>Pipeline, Parsers, Matchers, Organizers"]
APIExt["External APIs<br/>AI, TMDB Index"]
Mon["Watchdog Monitor"]
end
subgraph "Data"
DB["Database (SQLAlchemy/Alembic)"]
Cache["Cache Files"]
end
D --> SMain
T --> SMain
N --> SMain
SMain --> Routes
Routes --> Core
Core --> APIExt
Core --> DB
Mon --> DB
D --> DB

Section sources - apps/service/main.py - apps/service/app.py - apps/shared/db.py - alembic/env.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js - apps/dashboard/src/App.tsx - apps/tray/main.py - apps/notify/main.py

Core Components¶

FastAPI Application and Dependency Injection
Application factory and lifespan initialization
Centralized dependency provider module for database sessions, configuration, and services
API Routes
Authentication, configuration, decisions, history, media server (Jellyfin), logs, push notifications, status, tools, users
Core Business Logic
Pipeline orchestration, scanning, parsing (document and image), matching, organization, confidence scoring, decision modeling, use cases
External Integrations
AI services, TMDB indexing
Data Management
SQLAlchemy models and schemas, Alembic migrations
Monitoring and Background Processing
Watchdog monitor for file system events
Presentation Layer
Electron-packaged React dashboard with pages for home, config, history, decisions, logs, media server, and users
Desktop Integration
Tray app and notify service for OS-level interactions

Architecture Overview¶

The system follows a layered, service-oriented architecture: - Presentation Layer: Electron-hosted React dashboard, tray app, and notify service - API Services: FastAPI endpoints encapsulating domain operations - Core Business Logic: Pipeline orchestration, scanning, parsing, matching, organizing, and decisioning - Data Layer: SQLAlchemy models and Alembic migrations - External Integrations: AI and TMDB services - Event-Driven Processing: File system monitoring triggers pipeline execution

sequenceDiagram
participant UI as "Dashboard UI"
participant FE as "Electron Preload"
participant API as "FastAPI Routes"
participant Core as "Core Pipeline"
participant Ext as "External APIs"
participant DB as "Database"
UI->>FE : User action (e.g., scan, configure)
FE->>API : HTTP request to route
API->>Core : Invoke pipeline/usecase
Core->>Ext : Call AI/TMDB if needed
Core->>DB : Persist decisions/history/status
Core-->>API : Result or event stream
API-->>FE : Response/SSE event
FE-->>UI : Update view

Diagram sources - apps/dashboard/electron/preload.js - apps/dashboard/src/App.tsx - apps/service/routes/config.py - apps/service/routes/decisions.py - apps/service/routes/history.py - apps/service/routes/logs.py - apps/service/routes/status.py - apps/service/core/pipeline.py - apps/service/api/ai.py - apps/service/api/tmdb_index.py - apps/shared/db.py

Detailed Component Analysis¶

FastAPI Service Layer and Dependency Injection¶

Application lifecycle and middleware registration
Centralized dependency providers for database sessions, configuration, and services
Route modules encapsulate domain-specific endpoints

classDiagram
class FastAPIApp {
+lifespan()
+middleware()
+include_router()
}
class Deps {
+get_db_session()
+get_config()
+provide_services()
}
class Routes {
+auth_routes()
+config_routes()
+decisions_routes()
+history_routes()
+jellyfin_routes()
+logs_routes()
+push_routes()
+status_routes()
+tools_routes()
+users_routes()
}
FastAPIApp --> Deps : "uses"
FastAPIApp --> Routes : "includes"

Diagram sources - apps/service/app.py - apps/service/deps.py - apps/service/routes/auth.py - apps/service/routes/config.py - apps/service/routes/decisions.py - apps/service/routes/history.py - apps/service/routes/jellyfin.py - apps/service/routes/logs.py - apps/service/routes/push.py - apps/service/routes/status.py - apps/service/routes/tools.py - apps/service/routes/users.py

Section sources - apps/service/app.py - apps/service/deps.py - apps/service/routes/auth.py - apps/service/routes/config.py - apps/service/routes/decisions.py - apps/service/routes/history.py - apps/service/routes/jellyfin.py - apps/service/routes/logs.py - apps/service/routes/push.py - apps/service/routes/status.py - apps/service/routes/tools.py - apps/service/routes/users.py

Core Business Logic: Pipeline, Parsers, Matchers, Organizers¶

Pipeline orchestrates scanning, parsing, classification, matching, and organization steps
Plugin-style parsers for documents and images allow extensibility
Matcher and organizer implement decision-making and file movement strategies
Confidence scoring supports probabilistic decisions
Use cases encapsulate higher-level workflows

flowchart TD
Start(["Start Scan"]) --> Detect["Detect Media Items"]
Detect --> Parse["Parse Metadata<br/>Document/Image Parsers"]
Parse --> Classify["Classify Content"]
Classify --> Match["Match Against Known Entities"]
Match --> Score["Compute Confidence"]
Score --> Decide{"Decision Threshold?"}
Decide --> |Yes| Organize["Organize/Rename/Move"]
Decide --> |No| Log["Log Decision"]
Organize --> Persist["Persist Decisions/History"]
Log --> Persist
Persist --> End(["End"])

Diagram sources - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/parser.py - apps/service/core/document_parser.py - apps/service/core/image_parser.py - apps/service/core/matcher.py - apps/service/core/organizer.py - apps/service/core/confidence.py - apps/service/core/decision.py - apps/service/core/types.py - apps/service/core/usecases.py - apps/service/core/document_usecases.py - apps/service/core/image_usecases.py

Section sources - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/parser.py - apps/service/core/document_parser.py - apps/service/core/image_parser.py - apps/service/core/matcher.py - apps/service/core/organizer.py - apps/service/core/confidence.py - apps/service/core/decision.py - apps/service/core/types.py - apps/service/core/usecases.py - apps/service/core/document_usecases.py - apps/service/core/image_usecases.py

Database Models and Migrations¶

SQLAlchemy models define entities for actions, decisions, history, push subscriptions, status, and users
Schemas provide Pydantic validation for API payloads
Alembic manages schema evolution

erDiagram
ACTION_LOG {
int id PK
string action
text details
timestamp created_at
}
DECISION {
int id PK
string item_path
string decision_type
float confidence
json metadata
timestamp created_at
}
HISTORY {
int id PK
string item_path
string operation
text result
timestamp created_at
}
PUSH_SUBSCRIPTION {
int id PK
string endpoint
string p256dh
string auth
boolean active
}
STATUS {
int id PK
string key
string value
timestamp updated_at
}
USER {
int id PK
string username UK
string password_hash
boolean active
timestamp created_at
}

Diagram sources - apps/shared/models/action_log.py - apps/shared/models/decision.py - apps/shared/models/history.py - apps/shared/models/push_subscription.py - apps/shared/models/status.py - apps/shared/models/user.py - apps/shared/schemas/decision.py - apps/shared/schemas/history.py - apps/shared/schemas/user.py - apps/shared/schemas/auth.py - apps/shared/schemas/config.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py

Section sources - apps/shared/models/action_log.py - apps/shared/models/decision.py - apps/shared/models/history.py - apps/shared/models/push_subscription.py - apps/shared/models/status.py - apps/shared/models/user.py - apps/shared/schemas/decision.py - apps/shared/schemas/history.py - apps/shared/schemas/user.py - apps/shared/schemas/auth.py - apps/shared/schemas/config.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py

External Integrations: AI and TMDB¶

AI service integration for content analysis or enrichment
TMDB index service for media metadata lookup and synchronization

sequenceDiagram
participant API as "TMDB Route"
participant TMDB as "TMDB Index Service"
participant DB as "Database"
API->>TMDB : Fetch/Update metadata
TMDB-->>API : Metadata results
API->>DB : Persist references
API-->>Client : Responses

Diagram sources - apps/service/api/tmdb.py - apps/service/api/tmdb_index.py - apps/shared/db.py

Section sources - apps/service/api/ai.py - apps/service/api/tmdb.py - apps/service/api/tmdb_index.py

Monitoring and Event-Driven Processing¶

Watchdog monitors file system changes and triggers pipeline scans
Events can be propagated via internal queues or SSE to clients

flowchart TD
FS["File System Changes"] --> WD["Watchdog Monitor"]
WD --> Queue["Internal Event Queue"]
Queue --> Pipe["Pipeline Orchestrator"]
Pipe --> DB["Database Updates"]
Pipe --> SSE["SSE Events to Clients"]

Diagram sources - apps/service/monitor/watchdog.py - apps/service/core/pipeline.py - apps/service/routes/logs.py - apps/service/routes/status.py

Section sources - apps/service/monitor/watchdog.py - apps/service/routes/logs.py - apps/service/routes/status.py

Presentation Layer: Dashboard and Desktop Integration¶

Electron main process hosts the React UI and exposes IPC channels
Preload script bridges secure contexts to the renderer
Pages implement configuration, history, decisions, logs, media server, and user management
Tray app provides quick access and background control
Notify service handles OS notifications

graph TB
EM["Electron Main"] --> PP["Preload Script"]
PP --> RN["React Renderer"]
RN --> API["FastAPI Routes"]
EM --> Tray["Tray App"]
EM --> Notify["Notify Service"]

Diagram sources - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js - apps/dashboard/src/App.tsx - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Historico.tsx - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/MediaServer.tsx - apps/dashboard/src/pages/Usuarios.tsx - apps/tray/main.py - apps/notify/main.py

Section sources - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js - apps/dashboard/src/App.tsx - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Historico.tsx - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/MediaServer.tsx - apps/dashboard/src/pages/Usuarios.tsx - apps/tray/main.py - apps/notify/main.py

Dependency Analysis¶

Internal dependencies
Routes depend on core use cases and shared schemas/models
Core depends on parsers, matchers, organizers, and types
External APIs are isolated behind service modules
Database access is centralized through shared db module and Alembic
External dependencies
FastAPI, SQLAlchemy, Alembic, Pydantic, watchfiles/watchdog, and others defined in requirements

graph LR
Routes["API Routes"] --> Core["Core Modules"]
Core --> Parsers["Parsers"]
Core --> Matchers["Matchers"]
Core --> Organizers["Organizers"]
Core --> Types["Types"]
Core --> ExtAPI["External APIs"]
Routes --> Schemas["Shared Schemas"]
Core --> Models["Shared Models"]
Models --> DB["Database"]
DB --> Alembic["Alembic Migrations"]

Section sources - requirements.txt - apps/service/deps.py - apps/shared/db.py - alembic/env.py

Performance Considerations¶

Pipeline batching and chunked processing to reduce memory pressure during large scans
Asynchronous I/O for external API calls and database queries
Caching strategies for frequently accessed metadata (e.g., TMDB responses)
Efficient file system watching with debouncing to avoid redundant scans
Indexed database queries for decisions and history retrieval
Streaming logs and status updates via Server-Sent Events to minimize polling overhead

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Centralized Logging
Unified logger configuration for consistent log levels and formats across components
Error Handling Strategies
Route-level exception handlers returning structured errors
Core-level validation using Pydantic schemas to catch invalid inputs early
Configuration Management
Hierarchical configuration loading with environment overrides
Validation of required settings at startup
Security Implementation Patterns
Authentication and authorization checks in protected routes
Secure storage of credentials and tokens
Input sanitization and output encoding

Section sources - src/logger.py - apps/service/deps.py - apps/shared/config.py - apps/service/routes/auth.py - apps/shared/schemas/auth.py

Conclusion¶

Nexo implements a modular, service-oriented architecture that cleanly separates concerns across API services, core business logic, data management, and presentation layers. The microservices approach leverages FastAPI for responsive APIs, a robust processing pipeline for media discovery and organization, and a React-based dashboard for interactive control. Event-driven processing, plugin-style parsers, dependency injection, and centralized cross-cutting concerns contribute to maintainability and scalability.

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

Appendices¶

Technology Stack and Third-Party Dependencies¶

Backend: FastAPI, SQLAlchemy, Alembic, Pydantic
Frontend: React, TypeScript, Vite, Electron
Utilities: Watchdog for file system monitoring, logging frameworks
External APIs: AI services, TMDB

Section sources - requirements.txt