# antonychr/orus-media-server architecture

> Architecture diagram of the GitHub repository antonychr/orus-media-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antonychr/orus-media-server
- Repository: https://github.com/antonychr/orus-media-server

## Overview

##### Project type and purpose
- Orus is a full-stack media server:
- A Go-based backend binary that watches local media folders, syncs metadata via OMDB, stores info in SQLite, and exposes HTTP (REST + SSE) APIs.
- A React/Vite frontend (GUI) that runs in the browser, calling those APIs to display and manage media.

##### File structure
- Top level:
- main.go & internal/: Go application entry point + clean-architecture layers (delivery/controllers, domain/models/services/repos, infrastructure implementations).
- config/: TOML loading and tests.
- scripts/: Dev/build helpers.
- gui/: React+TypeScript app with src/components, data_fetching, providers, pages, layouts.
- utils/: shared Go helpers.
- Build & CI: .github/workflows, Makefile, go.mod, package.json under gui.

##### Read README for additional insights
- HTTP backend on PORT (default :3002), media & subtitle directories, SQLite DB, SSE for logs.
- Frontend dev on Vite :5173, production config page under /config.
- OMDB external API integration for metadata.

##### Main components
a. Client / Browser (React GUI)
b. Backend Service (Go binary)
- HTTP API layer (controllers in internal/delivery)
- Domain layer (services, models, repository interfaces)
- Infrastructure layer (SQLite repositories, file‐system watcher, OMDB provider, SSE log manager)
c. Local Resources
- File System: media/ and subtitles/ directories
- SQLite database file (database.db)
- Config (config.toml)
d. External Service: OMDB REST API

##### Relationships and interactions
- Browser ↔ HTTP API over REST endpoints (e.g. GET /titles, POST /subtitles)
- Browser ← SSE stream (server_logs_controller)
- Backend ↔ SQLite (CRUD via repository implementations)
- Backend ↔ File System watchers (media_event_handler → domain services → repositories)
- Backend → External OMDB API (fetch metadata when needed)
- Config values flow into all backend components (port, API_KEY, paths)

##### Architectural patterns & design principles
- Clean / Hexagonal architecture:
- Delivery layer depends on domain interfaces, not implementations.
- Domain services orchestrate business logic.
- Infrastructure implements repository and provider interfaces.
- Single‐responsibility: each package has one concern (config, delivery, domain, infrastructure).
- Observer pattern for file‐system events, SSE for real‐time logs.

##### Technologies & frameworks
- Backend: Go 1.20+, net/http (controllers & middlewares), SQLite, TOML config, OMDB REST.
- Frontend: React + TypeScript, Vite, Tailwind CSS, Context API for alerts & data, custom hooks, i18n, localStorage.
- CI/CD: GitHub Actions, Makefile, shell scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    Browser["React GUI (Port 5173)"]:::frontend
    click Browser "https://github.com/antonychr/orus-media-server/tree/main/gui/"

    %% Backend Service Container
    subgraph "Backend Service (Port 3002)"
        direction TB

        %% Delivery Layer
        subgraph "Delivery Layer"
            direction TB
            TitleInfoController["TitleInfoController"]:::backend
            VideoController["VideoController"]:::backend
            SubtitleController["SubtitleController"]:::backend
            ServerLogsController["ServerLogsController"]:::backend
            ConfigController["ConfigController"]:::backend
            SSEHeader["SSEHeader Middleware"]:::backend
            HandleRequest["RequestHandler Middleware"]:::backend
            RedirectMiddleware["Redirect Middleware"]:::backend
        end

        %% Domain Layer
        subgraph "Domain Layer"
            direction TB
            InfoService["InfoService"]:::backend
            MediaInfoSync["MediaInfoSync Service"]:::backend
            SubtitleService["SubtitleService"]:::backend
            TitleInfoService["TitleInfoService"]:::backend
            VideoService["VideoService"]:::backend
            RepoInterface["TitleInfoRepository Interface"]:::backend
            FileExplorer["MediaFileExplorer Interface"]:::backend
            ProviderInterface["TitleInfoProvider Interface"]:::backend
        end

        %% Infrastructure Layer
        subgraph "Infrastructure Layer"
            direction TB
            FSWatcher["MediaDirWatcher"]:::backend
            EventHandler["MediaEventHandlerService"]:::backend
            FileExplorerImpl["MediaFileExplorerImpl"]:::backend
            SSELogManager["LogSSEManager"]:::backend
            SQLiteTitleRepo["SQLiteTitleInfoRepository"]:::backend
            SQLiteVideoRepo["SQLiteVideoRepository"]:::backend
            SQLiteSubtitleRepo["SQLiteSubtitleRepository"]:::backend
            OMDBProvider["OMDBTitleInfoProvider"]:::backend
        end
    end

    %% Data Stores & Resources
    SQLiteDB["SQLite Database (database.db)"]:::database
    ConfigFile["Config File (config.toml)"]:::resources
    MediaFS["Media & Subtitle Folders"]:::resources
    OMDB["OMDB REST API"]:::external

    %% Connections
    Browser -->|REST Calls| TitleInfoController
    Browser -->|REST Calls| VideoController
    Browser -->|REST Calls| SubtitleController
    Browser -->|REST Calls| ConfigController
    ServerLogsController -->|SSE Stream| Browser

    TitleInfoController -->|calls| InfoService
    VideoController -->|calls| VideoService
    SubtitleController -->|calls| SubtitleService
    ConfigController -->|reads| ConfigFile

    FSWatcher -->|onEvent| EventHandler
    EventHandler -->|calls| MediaInfoSync
    MediaInfoSync -->|uses| RepoInterface
    SubtitleService -->|uses| RepoInterface
    TitleInfoService -->|uses| RepoInterface
    VideoService -->|uses| RepoInterface

    RepoInterface -->|implemented by| SQLiteTitleRepo
    RepoInterface -->|implemented by| SQLiteVideoRepo
    RepoInterface -->|implemented by| SQLiteSubtitleRepo

    SQLiteTitleRepo -->|CRUD| SQLiteDB
    SQLiteVideoRepo -->|CRUD| SQLiteDB
    SQLiteSubtitleRepo -->|CRUD| SQLiteDB

    ProviderInterface -->|implemented by| OMDBProvider
    OMDBProvider -->|HTTP| OMDB

    ConfigFile -->|provides| SSEHeader
    ConfigFile -->|provides| FSWatcher
    ConfigFile -->|provides| SQLiteTitleRepo

    %% Middleware wiring
    SSEHeader --> ServerLogsController
    HandleRequest --> TitleInfoController
    RedirectMiddleware --> VideoController

    %% File Explorer Impl
    FileExplorerImpl -->|implements| FileExplorer
    EventHandler --> FileExplorerImpl

    %% Click Events
    click Browser "https://github.com/antonychr/orus-media-server/tree/main/gui/"
    click TitleInfoController "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/controllers/Title_info_controller.go"
    click VideoController "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/controllers/video_controller.go"
    click SubtitleController "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/controllers/subtitle_controller.go"
    click ServerLogsController "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/controllers/server_logs_controller.go"
    click ConfigController "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/controllers/config_controller.go"
    click SSEHeader "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/middlewares/SSEHeader.go"
    click HandleRequest "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/middlewares/handle_req.go"
    click RedirectMiddleware "https://github.com/antonychr/orus-media-server/blob/main/internal/delivery/middlewares/redirect.go"
    click InfoService "https://github.com/antonychr/orus-media-server/blob/main/internal/domain/services/info_service.go"
    click MediaInfoSync "https://github.com/antonychr/orus-media-server/blob/main/internal/domain/services/media_info_sync.go"
    click SubtitleService "https://github.com/antonychr/orus-media-server/blob/main/internal/domain/services/subtitle_service.go"
    click TitleInfoService "https://github.com/antonychr/orus-media-server/blob/main/internal/domain/services/title_info_service.go"
    click VideoService "https://github.com/antonychr/orus-media-server/blob/main/internal/domain/services/video_service.go"
    click RepoInterface "https://github.com/antonychr/orus-media-server/blob/main/internal/domain/repositories/Title_info_repository.go"
    click FSWatcher "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/media_dir_watcher.go"
    click EventHandler "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/media_event_handler_service.go"
    click FileExplorerImpl "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/media_file_explorer_impl.go"
    click SSELogManager "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/LogSSEManager.go"
    click SQLiteTitleRepo "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/repositories/sqlite_title_info_repository.go"
    click SQLiteVideoRepo "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/repositories/sqlite_video_repository.go"
    click SQLiteSubtitleRepo "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/repositories/sqlite_subtitle_repo.go"
    click OMDBProvider "https://github.com/antonychr/orus-media-server/blob/main/internal/infrastructure/repositories/omdb_title_info_prov.go"
    click ConfigFile "https://github.com/antonychr/orus-media-server/blob/main/config/config.go"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#4B8BBE;
    classDef backend fill:#E0FFE0,stroke:#2E8B57;
    classDef database fill:#FFE0B2,stroke:#FF8C00;
    classDef external fill:#E0E0E0,stroke:#888888;
    classDef resources fill:#FFF5E6,stroke:#CC7A00;
```
