# vibioh/fibr architecture

> Architecture diagram of the GitHub repository vibioh/fibr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vibioh/fibr
- Repository: https://github.com/vibioh/fibr

## Overview

##### Project type and purpose
- **Type**: Full-stack, monolithic Go web application bundling frontend (HTML/CSS/JS) and backend in a single static binary.
- **Purpose**: Serve a mobile-friendly file-browser UI, manage files (CRUD), generate thumbnails & map views via sidecars, support sharing, webhooks, search, and telemetry.

##### File structure
- **cmd/fibr/**: Entrypoint, CLI flags, HTTP server, template & static assets loader, wiring of ports & adapters.
- **pkg/**: Core business logic layers by domain (crud, storage, metadata, thumbnail, webhook, search, share, provider, sanitizer).
- **infra/** & **compose.yaml**: Deployment manifests (Kubernetes, Docker-Compose).
- **Dockerfile**, **Makefile**, **.github/**: CI/CD & build tooling.

##### Key architectural insights from README
- Uses **HTML templates** + minimal JS for UI.
- Pluggable communication to sidecars via **HTTP** or **AMQP**.
- Storage can be local filesystem or S3-compatible object store.
- Optional **Redis** for caching, locking, Pub/Sub to coordinate multiple instances.
- Exposes **OpenTelemetry** metrics and optional **pprof** profiling.
- Webhooks to external HTTP endpoints with optional HTTP Signatures.

##### Main components & relationships
a. **User Browser** (Web UI)
- Issues HTTP(S) requests (GET, POST, chunked uploads) to fibr’s HTTP server.
b. **Fibr HTTP Server (cmd/fibr)**
- **Router & Handlers**: Serve static assets & templates, implement endpoints (`/health`, `/version`, `/files/*`, share links, webhooks, search).
- **Template Engine**: Renders Go HTML templates.
- **Domain Services (pkg/***)**:
- CRUD Service (browse, upload, delete, rename…)
- Share Service (create/read shares, password protection, expiration)
- Search Service (metadata lookup)
- Webhook Service (publish events)
- Thumbnail & Exif Orchestrator (dispatch tasks to sidecars)
- **Ports & Adapters**: Defined in `cmd/fibr/adapters.go` (file system adapter, AMQP client, HTTP client, Redis client, S3 client).
c. **Storage Layer**
- **Local FS**: Root folder + `.fibr` metadata subfolder.
- **Object Store**: S3-compatible (optional).
d. **Sidecar Services**
- **Thumbnail Service (vignet)**: HLS & WebP thumbnail generation.
- **Exif Service (exas)**: EXIF extraction & optional reverse-geocoding.
- Communication over HTTP or via **AMQP** broker.
e. **Message Broker (AMQP)**
- Exchanges & Queues for `thumbnail` and `exif` tasks and results.
f. **Redis** (optional)
- Locks & Pub/Sub for coordinating multiple instances, caching metadata.
g. **External HTTP Endpoints**
- Webhook subscribers receiving JSON events, signed with HTTP Signature.
h. **Observability**
- **OpenTelemetry** gRPC exporter for traces & metrics.
- **pprof** endpoint (optional).
- Metrics collected: HTTP latencies/status, AMQP operations, sidecar calls.

##### Architectural patterns & design principles
- **Hexagonal Architecture** (Ports & Adapters): Core logic decoupled from transport & persistence layers.
- **Modular Monolith**: Domain logic organized by feature in `pkg/`.
- **Single Binary Deployment**: All code + assets compiled into one Go executable.
- **Sidecar Pattern**: Offload CPU-intensive tasks to separate services.
- **Pub/Sub & Message-driven**: AMQP for resilient background processing.

##### Don’t overthink—capture all modules as sub‐components where relevant. E.g.,
- Under Domain: list `pkg/crud`, `pkg/share`, `pkg/search`, `pkg/metadata`, `pkg/thumbnail`, `pkg/webhook`.
- Under Adapters: file system, object storage, AMQP, HTTP (sidecars & webhooks), Redis.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    Browser["User Browser (Web UI)"]:::external
    AMQPBroker["AMQP Broker"]:::external
    RedisSys["Redis (Cache/Lock/PubSub)"]:::external
    ObjStore["Object Store (S3)"]:::external
    ThumbnailSvc["Thumbnail Sidecar (vignet)"]:::external
    ExifSvc["EXIF Sidecar (exas)"]:::external
    WebhookEP["Webhook Endpoints"]:::external
    OTelColl["OTel Collector"]:::external

    %% Core Service
    subgraph "Fibr Service"
        direction TB
        subgraph "HTTP Layer"
            direction TB
            HTTPEntry["Fibr HTTP Server Entry Point"]:::internal
            RouterHandlers["Router & Handlers"]:::internal
            TemplateEngine["Template Engine Adapter"]:::adapter
        end
        subgraph "Domain Layer"
            direction TB
            CRUD["CRUD Service"]:::domain
            Share["Share Service"]:::domain
            Search["Search Service"]:::domain
            WebhookDom["Webhook Service"]:::domain
            ThumbOrch["Thumbnail Orchestrator"]:::domain
            ExifOrch["EXIF Orchestrator"]:::domain
            Geo["Reverse-Geocoding (Geo)"]:::domain
        end
        subgraph "Adapter Layer"
            direction TB
            FSAdpt["File System Adapter"]:::adapter
            S3Adpt["Object Store (S3) Adapter"]:::adapter
            AMQPAdpt["AMQP Adapter"]:::adapter
            HTTPClnt["HTTP Client Adapter"]:::adapter
            RedisAdpt["Redis Adapter"]:::adapter
            Metrics["Observability / Metrics"]:::adapter
            Utils["Core Utilities"]:::internal
        end
    end

    %% Connections: Browser to HTTP
    Browser -->|"HTTP Requests"| RouterHandlers
    RouterHandlers -->|"renders"| TemplateEngine
    RouterHandlers -->|"invokes"| CRUD
    RouterHandlers -->|"invokes"| Share
    RouterHandlers -->|"invokes"| Search
    RouterHandlers -->|"invokes"| WebhookDom
    RouterHandlers -->|"invokes"| ThumbOrch
    RouterHandlers -->|"invokes"| ExifOrch

    %% Domain to Adapters
    CRUD -->|"uses FS/S3"| FSAdpt
    CRUD -->|"uses S3"| S3Adpt
    Share -->|"uses FS/S3"| FSAdpt
    Search -->|"uses FS/S3"| FSAdpt
    WebhookDom -->|"calls HTTPClnt"| HTTPClnt
    ThumbOrch -->|"publishes tasks"| AMQPAdpt
    ThumbOrch -->|"collects metrics"| Metrics
    ExifOrch -->|"publishes tasks"| AMQPAdpt
    Geo -->|"calls HTTPClnt"| HTTPClnt

    %% Adapters to External
    FSAdpt -->|"reads/writes"| Browser
    S3Adpt -->|"reads/writes"| ObjStore
    AMQPAdpt -->|"to/from"| AMQPBroker
    HTTPClnt -->|"to"| ThumbnailSvc
    HTTPClnt -->|"to"| ExifSvc
    HTTPClnt -->|"to"| WebhookEP
    RedisAdpt -->|"connects"| RedisSys
    Metrics -->|"exports"| OTelColl

    %% AMQP Task Flow
    AMQPBroker -->|"thumbnail events"| ThumbnailSvc
    ThumbnailSvc -->|"results"| AMQPBroker
    AMQPBroker -->|"exif events"| ExifSvc
    ExifSvc -->|"results"| AMQPBroker

    %% Click Events
    click Browser "https://github.com/vibioh/fibr/tree/main/cmd/fibr/static/"
    click Browser "https://github.com/vibioh/fibr/tree/main/cmd/fibr/templates/"
    click HTTPEntry "https://github.com/vibioh/fibr/blob/main/cmd/fibr/fibr.go"
    click RouterHandlers "https://github.com/vibioh/fibr/blob/main/cmd/fibr/services.go"
    click TemplateEngine "https://github.com/vibioh/fibr/blob/main/pkg/fibr/renderer.go"
    click CRUD "https://github.com/vibioh/fibr/tree/main/pkg/crud/"
    click Share "https://github.com/vibioh/fibr/tree/main/pkg/share/"
    click Search "https://github.com/vibioh/fibr/tree/main/pkg/search/"
    click WebhookDom "https://github.com/vibioh/fibr/tree/main/pkg/webhook/"
    click ThumbOrch "https://github.com/vibioh/fibr/tree/main/pkg/thumbnail/"
    click ExifOrch "https://github.com/vibioh/fibr/blob/main/pkg/metadata/exif.go"
    click FSAdpt "https://github.com/vibioh/fibr/blob/main/cmd/fibr/adapters.go"
    click S3Adpt "https://github.com/vibioh/fibr/blob/main/cmd/fibr/adapters.go"
    click S3Adpt "https://github.com/vibioh/fibr/blob/main/pkg/provider/storage.go"
    click AMQPAdpt "https://github.com/vibioh/fibr/blob/main/cmd/fibr/adapters.go"
    click AMQPAdpt "https://github.com/vibioh/fibr/blob/main/pkg/metadata/amqp.go"
    click AMQPAdpt "https://github.com/vibioh/fibr/blob/main/pkg/thumbnail/amqp.go"
    click HTTPClnt "https://github.com/vibioh/fibr/blob/main/cmd/fibr/clients.go"
    click RedisAdpt "https://github.com/vibioh/fibr/blob/main/cmd/fibr/clients.go"
    click Metrics "https://github.com/vibioh/fibr/blob/main/pkg/metadata/metric.go"
    click Metrics "https://github.com/vibioh/fibr/blob/main/pkg/thumbnail/metric.go"
    click Metrics "https://github.com/vibioh/fibr/blob/main/pkg/webhook/metric.go"

    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef domain fill:#e0ccff,stroke:#333,stroke-width:1px
    classDef adapter fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef external fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef infra fill:#f0f4c3,stroke:#333,stroke-width:1px
```
