Skip to content

System Architecture Overview

Referenced Files in This Document

Table of Contents

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

  10. Appendices

Introduction

This document describes the system architecture of Nexo, a modular service-oriented application that monitors media files, extracts metadata, applies decision logic, and exposes APIs for a React/TypeScript web dashboard and an Electron-based desktop wrapper. The backend is implemented with FastAPI, the data layer uses SQLAlchemy with Alembic migrations, and file monitoring is driven by Watchdog. External integrations include Jellyfin media server and AI/ML services. The architecture emphasizes clear separation between backend services, web dashboard, desktop packaging, and data layer, while supporting event-driven processing and a plugin-based parser system.

Project Structure

The repository organizes code into distinct layers:

  • Backend services (FastAPI): routes, core business logic, API integrations, and shared schemas/models

  • Data layer: SQLAlchemy models, database configuration, and Alembic migrations

  • Monitoring: Watchdog-based file system watcher

  • Dashboard: React/TypeScript SPA with Vite and Electron packaging

  • Shared: configuration, schemas, and models used across components

graph TB

subgraph "Backend Services"

SMain["apps/service/main.py"]

SApp["apps/service/app.py"]

Routes["apps/service/routes/*"]

Core["apps/service/core/*"]

APIExt["apps/service/api/*"]

Monitor["apps/service/monitor/watchdog.py"]

end

subgraph "Data Layer"

DBConf["apps/shared/db.py"]

Models["apps/shared/models/*"]

Schemas["apps/shared/schemas/*"]

Config["apps/shared/config.py"]

Alembic["alembic/*"]

end

subgraph "Dashboard"

DApp["apps/dashboard/src/App.tsx"]

Pages["apps/dashboard/src/pages/*"]

Hooks["apps/dashboard/src/hooks/*"]

EMain["apps/dashboard/electron/main.js"]

EPre["apps/dashboard/electron/preload.js"]

end

SMain --> SApp

SApp --> Routes

Routes --> Core

Core --> DBConf

Core --> Models

Core --> Schemas

Core --> Config

APIExt --> Core

Monitor --> Core

DApp --> |HTTP/SSE| SMain

EMain --> DApp

EPre --> DApp

Alembic --> DBConf

Diagram sources

Section sources

Core Components

  • FastAPI backend services:

  • Entry point and app initialization

  • Dependency injection setup

  • Route modules for authentication, configuration, decisions, history, logs, push notifications, status, tools, users, and Jellyfin integration

  • API clients for external services (AI/ML, TMDb)

  • Core business logic:

  • Pipeline orchestration for scanning, parsing, matching, organizing, and decision-making

  • Parser plugins for documents and images

  • Confidence scoring and matcher strategies

  • Use cases encapsulating domain operations

  • Data layer:

  • SQLAlchemy engine/session management

  • Declarative models for decisions, history, logs, users, push subscriptions, and status

  • Pydantic schemas for request/response validation

  • Alembic migration scripts for schema evolution

  • File monitoring:

  • Watchdog-based watcher triggering pipeline events on filesystem changes

  • Dashboard:

  • React/TypeScript SPA pages for home, decisions, history, logs, media server configuration, and user management

  • Hooks for real-time updates and section fetching

  • Electron main and preload scripts for desktop packaging

Section sources

Architecture Overview

The system follows a modular service-oriented design:

  • Backend services expose REST endpoints and optional Server-Sent Events for live updates

  • Core business logic orchestrates scanning, parsing, matching, organizing, and decision workflows

  • Data persistence is handled via SQLAlchemy with versioned migrations

  • Filesystem events trigger asynchronous processing through Watchdog

  • The React dashboard consumes APIs and displays results; Electron packages the UI for desktop distribution

  • External integrations include Jellyfin and AI/ML/TMDb services

graph TB

FS["File System<br/>Watchdog"] --> Monitor["Monitor Service<br/>watchdog.py"]

Monitor --> Pipeline["Pipeline Orchestrator<br/>pipeline.py"]

Pipeline --> Parsers["Parser Plugins<br/>document_parser.py, image_parser.py"]

Pipeline --> Matcher["Matcher & Confidence<br/>matcher.py, confidence.py"]

Pipeline --> Organizer["Organizer<br/>organizer.py"]

Pipeline --> Decider["Decision Logic<br/>decision.py"]

Decider --> DB["SQLAlchemy Models<br/>models/*"]

DB --> Migrations["Alembic Migrations<br/>alembic/*"]

API["FastAPI Routes<br/>routes/*"] --> Core["Use Cases & Types<br/>usecases.py, types.py"]

Core --> DB

API --> ExtAI["External AI/ML<br/>api/ai.py"]

API --> ExtTMDb["External TMDb<br/>api/tmdb.py, api/tmdb_index.py"]

API --> ExtJellyfin["External Jellyfin<br/>routes/jellyfin.py"]

Dashboard["React Dashboard<br/>src/pages/*"] --> API

Electron["Electron Wrapper<br/>electron/main.js, preload.js"] --> Dashboard

Diagram sources

Detailed Component Analysis

Backend Services (FastAPI)

  • Application bootstrap and dependency injection are centralized to ensure consistent configuration and resource lifecycle.

  • Route modules implement REST endpoints for:

  • Authentication and user management

  • Configuration management

  • Decision lifecycle and queries

  • History retrieval and filtering

  • Log streaming and inspection

  • Push notification subscriptions

  • System status reporting

  • Tools and utilities

  • Jellyfin integration endpoints

  • External API clients encapsulate calls to AI/ML services and TMDb indexing.

sequenceDiagram

participant Client as "Dashboard"

participant Router as "FastAPI Router"

participant UseCase as "Use Cases"

participant DB as "SQLAlchemy Models"

participant Ext as "External Services"

Client->>Router : "HTTP Request"

Router->>UseCase : "Invoke business operation"

UseCase->>DB : "Read/Write entities"

UseCase->>Ext : "Call AI/TMDb/Jellyfin"

Ext-->>UseCase : "Response"

UseCase-->>Router : "Result DTO"

Router-->>Client : "HTTP Response"

Diagram sources

Section sources

Core Business Logic and Pipeline

  • Pipeline orchestrates scanning, parsing, matching, organizing, and decision steps.

  • Parser plugins support multiple content types (documents, images).

  • Matcher and confidence modules evaluate similarity and reliability.

  • Organizer handles file movement or tagging based on decisions.

  • Use cases encapsulate domain operations and coordinate interactions with the data layer and external services.

flowchart TD

Start(["Start"]) --> Scan["Scan Filesystem"]

Scan --> Parse["Parse Content<br/>Document/Image"]

Parse --> Match["Match Metadata<br/>Similarity/Confidence"]

Match --> Organize["Organize/Tag Files"]

Organize --> Decide["Apply Decision Rules"]

Decide --> Persist["Persist Results<br/>Models + Logs"]

Persist --> End(["End"])

Diagram sources

Section sources

Data Layer (SQLAlchemy + Alembic)

  • Centralized database configuration and session management.

  • Declarative models represent core entities such as decisions, history, action logs, users, push subscriptions, and status.

  • Pydantic schemas define validated request/response payloads.

  • Alembic manages schema migrations and versioning.

erDiagram

DECISION {

uuid id PK

string title

string type

float confidence

timestamp created_at

timestamp updated_at

}

HISTORY {

uuid id PK

string action

text details

timestamp occurred_at

}

ACTION_LOG {

uuid id PK

string level

string message

timestamp logged_at

}

USER {

uuid id PK

string username UK

string password_hash

boolean active

timestamp created_at

}

PUSH_SUBSCRIPTION {

uuid id PK

string endpoint

string auth_token

string p256dh_key

boolean active

}

STATUS {

uuid id PK

string key UK

json value

timestamp updated_at

}

DECISION ||--o{ HISTORY : "generates"

USER ||--o{ PUSH_SUBSCRIPTION : "owns"

Diagram sources

Section sources

File Monitoring (Watchdog)

  • Watches configured directories for filesystem events (create, modify, delete).

  • Emits events to the pipeline for processing, enabling near-real-time ingestion.

sequenceDiagram

participant FS as "File System"

participant WD as "Watchdog Monitor"

participant Pipe as "Pipeline"

participant DB as "Database"

FS-->>WD : "Event : create/modify/delete"

WD->>Pipe : "Dispatch event"

Pipe->>DB : "Record action log"

Pipe-->>WD : "Processing result"

Diagram sources

Section sources

Web Dashboard and Desktop Packaging

  • React/TypeScript SPA provides pages for Home, Decisions, History, Logs, Media Server configuration, and Users.

  • Hooks manage real-time updates and section data fetching.

  • Electron main and preload scripts package the SPA for desktop distribution.

graph TB

App["App.tsx"] --> Home["Home.tsx"]

App --> Decidir["Decidir.tsx"]

App --> Historico["Historico.tsx"]

App --> Logs["Logs.tsx"]

App --> MediaServer["MediaServer.tsx"]

App --> Usuarios["Usuarios.tsx"]

Hooks["usePush.ts, useSectionFetch.ts"] --> App

ElectronMain["electron/main.js"] --> App

Preload["electron/preload.js"] --> App

Diagram sources

Section sources

Dependency Analysis

  • Backend services depend on:

  • Core business logic modules for processing pipelines and domain rules

  • Data layer for persistence and schema validation

  • External API clients for AI/ML and TMDb

  • Watchdog monitor for event-driven ingestion

  • Dashboard depends on:

  • Backend HTTP/SSE endpoints

  • Electron runtime for desktop packaging

graph LR

Routes["Routes"] --> Core["Core Modules"]

Core --> Models["Models"]

Core --> Schemas["Schemas"]

Core --> Config["Config"]

Core --> ExtAI["AI/ML API"]

Core --> ExtTMDb["TMDb API"]

Monitor["Watchdog"] --> Core

Dashboard["Dashboard"] --> Routes

Electron["Electron"] --> Dashboard

Diagram sources

Section sources

Performance Considerations

  • Asynchronous processing: Offload heavy parsing and matching tasks to background workers to keep API responsiveness high.

  • Database efficiency: Use connection pooling, selective queries, and indexes on frequently filtered fields (e.g., timestamps, types).

  • Caching: Cache external API responses (TMDb) and computed metadata where appropriate to reduce latency and rate limits.

  • Event batching: Batch filesystem events to avoid redundant processing during rapid file changes.

  • Streaming logs: Use Server-Sent Events or WebSocket streams for efficient log delivery to the dashboard.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Database connectivity issues:

  • Verify SQLAlchemy configuration and credentials

  • Ensure Alembic migrations are applied before startup

  • External service failures:

  • Implement retries and circuit breakers for AI/ML and TMDb calls

  • Surface meaningful error messages to the dashboard

  • Filesystem watcher problems:

  • Check permissions and watch paths

  • Debounce events to prevent overload

  • Real-time updates:

  • Validate SSE/WebSocket connections and reconnection logic in the dashboard hooks

Section sources

Conclusion

Nexo’s architecture separates concerns across backend services, core business logic, data persistence, monitoring, and frontend interfaces. The event-driven pipeline enables responsive processing of filesystem changes, while the dashboard provides interactive control and visibility. External integrations are encapsulated behind API clients, and migrations ensure schema evolution. This design supports scalability, maintainability, and extensibility through plugin-based parsers and well-defined service boundaries.

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

Appendices

System Context Diagram

Illustrates overall deployment topology including external systems.

graph TB

subgraph "Local Environment"

FE["React Dashboard (SPA)"]

Electron["Electron Wrapper"]

BE["FastAPI Backend"]

DB["SQLAlchemy + SQLite/PostgreSQL"]

Watchdog["Watchdog Monitor"]

end

subgraph "External Systems"

Jellyfin["Jellyfin Media Server"]

AIML["AI/ML Services"]

TMDb["TMDb API"]

end

FE --> BE

Electron --> FE

Watchdog --> BE

BE --> DB

BE --> Jellyfin

BE --> AIML

BE --> TMDb

Diagram sources