Skip to content

Getting Started Guide

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 guide helps you install, configure, and run Nexo for the first time. You will set up Python and Node.js, install dependencies, initialize the database with Alembic migrations, create your first user account, scan a video directory, review AI-generated decisions, approve classifications, and explore the dashboard. The guide includes both development and production environment notes and provides verification steps to ensure everything is working correctly.

Project Structure

Nexo consists of:

  • A Python backend service (FastAPI-based) that exposes APIs for scanning, decisions, history, configuration, users, and status.

  • An embedded web dashboard built with React/Vite and served by the backend.

  • Database schema management via Alembic.

  • Optional tray and notification utilities.

graph TB

subgraph "Python Backend"

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

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

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

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

AlembicEnv["alembic/env.py"]

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

end

subgraph "Dashboard (Frontend)"

DashPkg["apps/dashboard/package.json"]

DashVite["apps/dashboard/vite.config.ts"]

end

subgraph "Database"

DBFile["SQLite file (configured)"]

end

SvcMain --> SvcApp

SvcApp --> API_Routes

SvcApp --> SharedCfg

SvcApp --> SharedDB

SharedDB --> DBFile

AlembicEnv --> DBFile

SvcMain --> DashPkg

SvcMain --> DashVite

Diagram sources

Section sources

Core Components

  • Backend service entrypoint and application factory

  • Configuration module for runtime settings

  • Database connection and session management

  • Alembic migration runner and versions

  • Dashboard frontend build and packaging

Key responsibilities:

  • Service startup and route registration

  • Loading configuration from environment or config files

  • Initializing database connections and running migrations

  • Serving the compiled dashboard assets

  • Exposing REST endpoints for scanning, decisions, history, users, and logs

Section sources

Architecture Overview

The system runs as a single process that hosts:

  • FastAPI backend with multiple routes

  • Embedded static assets for the dashboard

  • SQLite database managed by Alembic

sequenceDiagram

participant User as "User"

participant Browser as "Web Browser"

participant Backend as "FastAPI Service"

participant Routes as "API Routes"

participant DB as "SQLite (via SQLAlchemy)"

participant Migrations as "Alembic"

User->>Browser : Open http : //localhost : port

Browser->>Backend : GET /dashboard (or root)

Backend-->>Browser : Serve compiled dashboard assets

User->>Browser : Login via dashboard

Browser->>Backend : POST /api/auth/login

Backend->>Routes : Authenticate request

Routes->>DB : Validate credentials

DB-->>Routes : User record

Routes-->>Backend : Auth token

Backend-->>Browser : Session/token response

User->>Browser : Start Scan

Browser->>Backend : POST /api/scan

Backend->>Routes : Schedule scan job

Routes->>DB : Persist scan status/history

DB-->>Routes : OK

Routes-->>Backend : Job ID/status

Backend-->>Browser : Scan started

Diagram sources

Detailed Component Analysis

Installation and Environment Setup

  • System requirements

  • Python 3.x (use a virtual environment)

  • Node.js (for building the dashboard if needed)

  • Install Python dependencies

  • Use pip to install packages listed in the project’s requirements file.

  • Install dashboard dependencies

  • Navigate to the dashboard directory and install Node.js dependencies using npm.

Verification steps:

  • Confirm Python version and pip availability.

  • Confirm Node.js and npm are installed.

  • Ensure the virtual environment is activated before installing packages.

Section sources

Initial Configuration

  • Application settings

  • Review and adjust configuration values such as database path, server host/port, logging level, and feature flags.

  • Environment variables

  • For production, prefer environment variables over hard-coded values.

  • Secrets and keys

  • Store secrets securely; avoid committing sensitive values to source control.

Where to look:

  • Backend configuration module

  • Service app initialization

Section sources

Database Setup with Alembic

  • Initialize and upgrade the database

  • Run Alembic upgrades to apply all migrations against the configured database URL.

  • Verify migrations

  • Check that tables exist and schema matches expected versions.

Migration files:

  • Initial schema

  • Additional decision type field

Section sources

First Run Walkthrough

  • Start the backend service

  • Launch the main service entrypoint.

  • Access the dashboard

  • Open the provided URL in your browser.

  • Create your first user account

  • Use the user management page to add an admin or operator account.

  • Configure a video directory

  • Add a folder path to scan in the configuration or via the appropriate endpoint.

  • Run a scan

  • Trigger a scan from the dashboard or API.

  • Review AI-generated decisions

  • Inspect suggested classifications and confidence scores.

  • Approve or reject decisions

  • Accept or modify suggestions to finalize classification.

  • Explore history and logs

  • View past scans, decisions, and system logs.

Expected outcomes:

  • New user exists in the database

  • Scan job completes and appears in history

  • Decisions table contains entries with approved/rejected states

  • Dashboard shows updated statistics and logs

Section sources

Development vs Production Environments

  • Development

  • Enable verbose logging

  • Use local paths for media directories

  • Keep default ports unless conflicts occur

  • Production

  • Set secure host binding and port

  • Use environment variables for secrets

  • Configure proper logging rotation and monitoring

  • Ensure database backups and permissions are correct

Section sources

Dependency Analysis

High-level dependency relationships:

  • The service depends on shared configuration and database modules.

  • The dashboard package defines frontend dependencies and build scripts.

  • Alembic manages database schema evolution.

graph LR

Req["requirements.txt"] --> PyDeps["Python Dependencies"]

PkgJson["apps/dashboard/package.json"] --> NpmDeps["Node.js Dependencies"]

SvcMain["apps/service/main.py"] --> SvcApp["apps/service/app.py"]

SvcApp --> SharedCfg["apps/shared/config.py"]

SvcApp --> SharedDB["apps/shared/db.py"]

SharedDB --> DB["SQLite"]

AlembicEnv["alembic/env.py"] --> DB

Diagram sources

Section sources

Performance Considerations

  • Prefer SSD storage for the media library and database to reduce I/O latency.

  • Tune concurrency limits based on CPU cores and available memory.

  • Adjust log verbosity in development; keep it minimal in production.

  • Monitor database size and consider periodic maintenance tasks.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Port already in use

  • Change the service port in configuration or stop the conflicting process.

  • Database errors

  • Re-run Alembic upgrades; verify the database URL and file permissions.

  • Missing Python packages

  • Reinstall dependencies from the requirements file inside the active virtual environment.

  • Dashboard not loading

  • Ensure the dashboard assets are built and accessible; check the service logs for asset serving errors.

  • Authentication failures

  • Verify user creation and password hashing; reset credentials if necessary.

Verification checklist:

  • Service starts without errors

  • Dashboard loads at the configured URL

  • Login succeeds with created user

  • Scan completes and appears in history

  • Decisions are visible and can be approved

Section sources

Conclusion

You have installed Nexo, initialized the database, created a user, scanned a video directory, reviewed AI-generated decisions, and explored the dashboard. With these steps, you can begin organizing your media library effectively. For ongoing operations, refer to the dashboard pages for configuration, decisions, history, and logs.

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

Appendices

Appendix A: Quick Commands

  • Install Python dependencies

  • Use pip with the requirements file.

  • Install dashboard dependencies

  • Use npm in the dashboard directory.

  • Upgrade database schema

  • Run Alembic upgrade to head.

  • Start the service

  • Execute the service entrypoint.

Section sources

Appendix B: Configuration Reference

  • Where to find configuration

  • Backend configuration module and service app initialization.

  • Typical settings

  • Database URL/path, server host/port, logging level, feature toggles.

Section sources

Appendix C: Migration Reference

  • Migration files

  • Initial schema and additional fields.

  • How to roll back safely

  • Use Alembic downgrade with caution and ensure data backups.

Section sources