Technology Stack¶

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 technology stack of Nexo, including backend and frontend frameworks, desktop packaging, database management, file system monitoring, AI/ML libraries, build tools, testing utilities, and platform compatibility. It explains why each technology was chosen, how they integrate, and provides guidance for extending or replacing components across Windows, macOS, and Linux.

Project Structure¶

The project is organized into: - Backend service (FastAPI-based) under apps/service with routes, core logic, shared models/schemas, and a watchdog monitor. - Frontend dashboard (React/TypeScript/Vite) under apps/dashboard, packaged as a desktop app via Electron. - Database migrations managed by Alembic. - Build and release scripts at the repository root. - Shared configuration and dependency definitions at the repository root.

graph TB
subgraph "Backend Service"
SMain["apps/service/main.py"]
SApp["apps/service/app.py"]
SRoutes["apps/service/routes/*"]
SCores["apps/service/core/*"]
SShared["apps/shared/*"]
SWatch["apps/service/monitor/watchdog.py"]
end
subgraph "Frontend Dashboard"
FPackage["apps/dashboard/package.json"]
FVite["apps/dashboard/vite.config.ts"]
FElectronPkg["apps/dashboard/electron/package.json"]
FEMain["apps/dashboard/electron/main.js"]
FPreload["apps/dashboard/electron/preload.js"]
end
subgraph "Database"
AIni["alembic.ini"]
AEnv["alembic/env.py"]
AMig1["alembic/versions/001_initial_schema.py"]
AMig2["alembic/versions/002_add_decision_type.py"]
SDB["apps/shared/db.py"]
SModels["apps/shared/models/*"]
end
subgraph "Build & Release"
BRoot["build.py"]
BV2["build-v2.py"]
Rel["release.py"]
end
SMain --> SApp
SApp --> SRoutes
SRoutes --> SCores
SRoutes --> SShared
SCores --> SShared
SWatch --> SCores
FPackage --> FVite
FElectronPkg --> FEMain
FEMain --> FPreload
AIni --> AEnv
AEnv --> AMig1
AEnv --> AMig2
SDB --> SModels
BRoot --> SMain
BV2 --> SMain
Rel --> SMain

Diagram sources - apps/service/main.py - apps/service/app.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 - apps/service/core/pipeline.py - apps/service/core/image_classifier.py - apps/service/core/document_parser.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/monitor/watchdog.py - apps/shared/db.py - apps/shared/models/init.py - apps/shared/models/user.py - apps/shared/models/decision.py - apps/shared/models/history.py - apps/shared/models/action_log.py - apps/shared/models/push_subscription.py - apps/shared/models/status.py - apps/dashboard/package.json - apps/dashboard/vite.config.ts - apps/dashboard/electron/package.json - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js - alembic.ini - alembic/env.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py - build.py - build-v2.py - release.py

Section sources - apps/service/main.py - apps/service/app.py - apps/dashboard/package.json - apps/dashboard/vite.config.ts - apps/dashboard/electron/package.json - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js - alembic.ini - alembic/env.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py - apps/shared/db.py - apps/shared/models/init.py - apps/shared/models/user.py - apps/shared/models/decision.py - apps/shared/models/history.py - apps/shared/models/action_log.py - apps/shared/models/push_subscription.py - apps/shared/models/status.py - apps/service/core/pipeline.py - apps/service/core/image_classifier.py - apps/service/core/document_parser.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/monitor/watchdog.py - build.py - build-v2.py - release.py

Core Components¶

Python backend with FastAPI: Provides REST APIs, dependency injection, and modular routing. See service entry points and route modules.
React/TypeScript frontend with Vite: Modern UI tooling with fast builds and hot reload.
Electron: Packages the web dashboard into a native desktop application with preload security boundaries.
SQLAlchemy ORM + Alembic: Declarative data models and migration tooling for schema evolution.
Watchdog: File system event monitoring to trigger scanning and processing pipelines.
AI/ML libraries: Used within image classification, document parsing, matching, and confidence scoring modules.
Build and release automation: Scripts orchestrate building, packaging, and releasing artifacts.

Key integration points: - Frontend communicates with the backend via HTTP APIs. - Electron main process serves the built frontend and bridges OS-level features through a preload script. - Watchdog monitors directories and invokes core pipeline modules. - Alembic manages database schema changes; models are defined declaratively.

Section sources - apps/service/main.py - apps/service/app.py - apps/dashboard/package.json - apps/dashboard/vite.config.ts - apps/dashboard/electron/package.json - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js - alembic.ini - alembic/env.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py - apps/shared/db.py - apps/shared/models/init.py - apps/service/monitor/watchdog.py - apps/service/core/pipeline.py - apps/service/core/image_classifier.py - apps/service/core/document_parser.py - apps/service/core/matcher.py - apps/service/core/confidence.py

Architecture Overview¶

High-level architecture showing how components interact:

graph TB
Client["Browser / Desktop App"] --> Electron["Electron Main Process"]
Electron --> WebUI["Vite-built Frontend"]
WebUI --> API["FastAPI Service"]
API --> Routes["Route Handlers"]
Routes --> Core["Core Logic Modules"]
Core --> Models["SQLAlchemy Models"]
Core --> Watchdog["Filesystem Monitor"]
Models --> DB["Database"]
Core --> AI["AI/ML Libraries"]
Core --> TMDB["TMDB Integration"]

Diagram sources - apps/dashboard/electron/main.js - apps/dashboard/vite.config.ts - apps/service/main.py - apps/service/app.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 - apps/service/core/pipeline.py - apps/service/core/image_classifier.py - apps/service/core/document_parser.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/api/ai.py - apps/service/api/tmdb.py - apps/service/monitor/watchdog.py - apps/shared/db.py - apps/shared/models/init.py

Detailed Component Analysis¶

Backend: FastAPI Application¶

Entry point initializes the FastAPI app, registers middleware, and mounts routers.
Dependency injection centralizes shared resources (database sessions, config).
Route modules implement domain endpoints (auth, config, decisions, history, jellyfin, logs, push, status, tools, users).
Core modules encapsulate business logic (pipeline orchestration, image/document parsing, matching, confidence scoring).

sequenceDiagram
participant FE as "Frontend/Electron"
participant API as "FastAPI App"
participant Router as "Route Handler"
participant Core as "Core Module"
participant DB as "SQLAlchemy Session"
participant FS as "Watchdog Monitor"
FE->>API : HTTP Request
API->>Router : Dispatch to route
Router->>Core : Invoke business logic
Core->>DB : Read/Write entities
Core-->>Router : Result
Router-->>FE : JSON Response
FS-->>Core : Filesystem events trigger processing

Frontend: React/TypeScript with Vite¶

package.json defines dependencies and scripts for development and production builds.
vite.config.ts configures dev server, proxying, and asset handling.
The dashboard is served during development and bundled for production.

flowchart TD
DevStart["npm/yarn/bun dev"] --> Vite["Vite Dev Server"]
Vite --> Proxy["Proxy to FastAPI"]
ProdBuild["npm/yarn/bun build"] --> Bundle["Static Assets"]
Bundle --> Serve["Served by Electron"]

Diagram sources - apps/dashboard/package.json - apps/dashboard/vite.config.ts

Section sources - apps/dashboard/package.json - apps/dashboard/vite.config.ts

Desktop Packaging: Electron¶

electron/package.json declares Electron runtime and dependencies.
electron/main.js bootstraps the Electron app and loads the built frontend.
electron/preload.js exposes secure IPC bridges to the renderer.

sequenceDiagram
participant OS as "Operating System"
participant EM as "Electron Main"
participant Pre as "Preload Script"
participant Renderer as "Renderer (React)"
participant API as "FastAPI Service"
OS->>EM : Launch App
EM->>Renderer : Load Built UI
Renderer->>Pre : Secure IPC Calls
Pre->>API : HTTP Requests
API-->>Pre : Responses
Pre-->>Renderer : Data

Diagram sources - apps/dashboard/electron/package.json - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js

Section sources - apps/dashboard/electron/package.json - apps/dashboard/electron/main.js - apps/dashboard/electron/preload.js

Database Management: SQLAlchemy + Alembic¶

alembic.ini configures the migration environment.
alembic/env.py sets up engine and metadata for migrations.
Versioned migrations define schema changes.
apps/shared/db.py provides session management and engine configuration.
apps/shared/models defines declarative models used by the application.

erDiagram
USER {
uuid id PK
string username
string password_hash
boolean active
timestamp created_at
timestamp updated_at
}
DECISION {
uuid id PK
string type
string source
string target
float confidence
timestamp created_at
timestamp updated_at
}
HISTORY {
uuid id PK
string action
string details
timestamp created_at
}
ACTION_LOG {
uuid id PK
string level
string message
timestamp created_at
}
PUSH_SUBSCRIPTION {
uuid id PK
string endpoint
string p256dh
string auth
timestamp created_at
}
STATUS {
uuid id PK
string key
string value
timestamp updated_at
}
USER ||--o{ DECISION : "creates"
USER ||--o{ HISTORY : "performs"
USER ||--o{ ACTION_LOG : "generates"
USER ||--o{ PUSH_SUBSCRIPTION : "subscribes"
USER ||--o{ STATUS : "manages"

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

Section sources - alembic.ini - alembic/env.py - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py - apps/shared/db.py - apps/shared/models/init.py - apps/shared/models/user.py - apps/shared/models/decision.py - apps/shared/models/history.py - apps/shared/models/action_log.py - apps/shared/models/push_subscription.py - apps/shared/models/status.py

File System Monitoring: Watchdog¶

The watchdog module listens for filesystem events and triggers processing workflows.
Integrates with core pipeline modules to handle new or modified media files.

flowchart TD
Start(["Watchdog Start"]) --> Watch["Monitor Directories"]
Watch --> Event{"Event Detected?"}
Event --> |No| Wait["Wait for Events"]
Event --> |Yes| Queue["Queue Task"]
Queue --> Pipeline["Invoke Core Pipeline"]
Pipeline --> Done(["Complete"])
Wait --> Event

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

Section sources - apps/service/monitor/watchdog.py - apps/service/core/pipeline.py

AI/ML and Content Analysis¶

Image classifier and document parser modules perform content analysis.
Matcher and confidence modules evaluate similarity and decision quality.
API layer integrates external AI services where applicable.

classDiagram
class ImageClassifier {
+classify(image_path) Result
+extract_features(image_path) Vector
}
class DocumentParser {
+parse(file_path) ParsedData
+extract_metadata(file_path) Metadata
}
class Matcher {
+match(source, target) Score
+rank(candidates) RankedList
}
class Confidence {
+compute(features) Float
+threshold(score) Decision
}
class AIService {
+call_api(payload) Response
+parse_response(response) Data
}
ImageClassifier --> Matcher : "provides features"
DocumentParser --> Matcher : "provides text/features"
Matcher --> Confidence : "scores"
AIService --> ImageClassifier : "optional enhancement"

Diagram sources - apps/service/core/image_classifier.py - apps/service/core/document_parser.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/api/ai.py

Section sources - apps/service/core/image_classifier.py - apps/service/core/document_parser.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/api/ai.py

External Integrations: TMDB¶

TMDB API client handles metadata retrieval and indexing.
Integrated into decision-making and enrichment workflows.

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

Dependency Analysis¶

Python dependencies are declared in requirements.txt and setup.py.
Frontend dependencies are declared in apps/dashboard/package.json.
Electron runtime and dependencies are declared in apps/dashboard/electron/package.json.
Alembic configuration is in alembic.ini and env.py.

graph LR
Req["requirements.txt"] --> Backend["Python Backend"]
Setup["setup.py"] --> Backend
FPkg["apps/dashboard/package.json"] --> Frontend["React/TS + Vite"]
EPkg["apps/dashboard/electron/package.json"] --> Electron["Electron Runtime"]
AIni["alembic.ini"] --> Migrations["Alembic Migrations"]
AEnv["alembic/env.py"] --> Migrations

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

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

Performance Considerations¶

Use connection pooling and efficient queries in SQLAlchemy sessions.
Cache frequently accessed metadata (e.g., TMDB results) to reduce network overhead.
Parallelize independent tasks in the pipeline where safe.
Optimize image/document parsing by streaming large inputs and avoiding unnecessary copies.
Configure Vite for production builds with code splitting and minification.
Tune Electron memory settings for large datasets.

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Verify database migrations align with current models before starting the service.
Check route registration and dependency injection wiring if endpoints fail.
Ensure Watchdog has read permissions on monitored directories.
Validate Electron preload security context when using IPC.
Inspect logs from route handlers and core modules for errors.

Section sources - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.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 - apps/service/monitor/watchdog.py - apps/dashboard/electron/preload.js

Conclusion¶

Nexo combines a FastAPI backend, a React/TypeScript frontend built with Vite, and Electron for desktop distribution. SQLAlchemy and Alembic provide robust data modeling and migration management. Watchdog enables reactive processing based on filesystem events, while AI/ML modules support advanced content analysis. The stack is modular and extensible, allowing replacement or augmentation of components while maintaining clear integration boundaries.

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

Appendices¶

Build Tools and Utilities¶

Repository-root scripts coordinate building and releasing artifacts.
Frontend build tooling configured via Vite.
Electron packaging driven by its own package manifest.

Section sources - build.py - build-v2.py - release.py - apps/dashboard/vite.config.ts - apps/dashboard/electron/package.json

Platform Compatibility¶

Python backend runs on Windows, macOS, and Linux; ensure compatible versions of dependencies.
Electron supports all major platforms; verify native binaries and system libraries.
Vite frontend assets are platform-agnostic; serve them via Electron or a web server.
Database drivers must match the target platform and deployment environment.

Section sources - apps/dashboard/electron/package.json - apps/service/main.py - apps/shared/db.py

Extending or Replacing Components¶

Add new FastAPI routes by creating a route module and mounting it in the app initialization.
Introduce new SQLAlchemy models and corresponding Alembic migrations.
Extend the pipeline by adding steps in core modules and invoking them from the orchestrator.
Replace AI providers by implementing adapters behind consistent interfaces.
Swap file monitoring backends by abstracting event sources behind a common interface.

Section sources - apps/service/app.py - apps/service/deps.py - apps/service/core/pipeline.py - apps/service/core/image_classifier.py - apps/service/core/document_parser.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/monitor/watchdog.py - alembic/env.py