# stefanwerfling/flyingfish architecture

> Architecture diagram of the GitHub repository stefanwerfling/flyingfish, 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/stefanwerfling/flyingfish
- Repository: https://github.com/stefanwerfling/flyingfish

## Overview

##### Project Type & Purpose
- FlyingFish is a full-stack, microservice-based reverse-proxy manager. It delivers a web UI (SPA), a central API/backend service, and several supporting services (DNS server, SSH server, DynDNS server, UPNP, VPN) orchestrated via Docker Compose. It leverages a plugin system, internal libraries (“core”, “schemas”), and communicates with external providers (Let’s Encrypt ACME, IP-location/databases, DynDNS providers).

##### Main Components
a. Ingress Layer
- Nginx reverse‐proxy (container “nginx”): routes “/” to the frontend static files, proxies “/api” and service endpoints to internal services.
b. User Interface
- Frontend SPA (container “frontend”): static assets, TypeScript/JavaScript, calls backend REST endpoints over HTTPS.
c. API / Control Plane
- Backend service (container “backend”): Node.js + TypeScript HTTP server (Express-like), hosts routes under “/Routes”, uses core library, plugin manager, performs business logic.
d. Supporting Microservices
- ddnsserver: Dynamic DNS HTTP API
- sshserver: SSH management API
- himhip: “How is my Public IP” service API
- vpn: VPN server management API
e. Shared Libraries
- core package: common DB layers (MariaDB, InfluxDB, Redis), plugin system, utilities
- schemas package: TypeScript schema definitions, validation
f. Data Stores
- MariaDB: primary relational DB for users, domains, credentials, settings.
- InfluxDB: time-series storage for Nginx access logs, stream requests.
- Redis: pub/sub channels, caching (e.g., UPNP).

##### Component Interactions & Data Flow
- Clients (browser) → Nginx (HTTPS) → Frontend assets OR → Proxy “/api/*” → Backend
- Backend ←→ MariaDB (CRUD) & InfluxDB (read/write) & Redis (cache/pub-sub)
- Backend ↔ Plugin modules (loaded at startup via PluginManager)
- Backend ↔ Supporting services (HTTP calls to ddnsserver, sshserver, himhip, vpn)
- Backend ↔ External provider APIs (Let’s Encrypt ACME, DNS providers, IP location services)
- nginx service also proxies traffic to managed upstreams (user-defined HTTP/stream routes).

##### Architectural Patterns & Principles
- Microservices: each service in its own container, single responsibility.
- Layered architecture in backend/core:
- Routes (API layer) → Service classes (business logic) → Data providers (Db/Cache/External API abstractions).
- Plugin System for extensibility via DI and event hooks.
- Infrastructure as code: Dockerfiles per service, docker-compose.yml for orchestration.
- Typed schema validation: ETS/VTS libraries via schemas package.

## Diagram (Mermaid)

```mermaid
graph TD
    %% UI Layer
    subgraph "UI Layer"
        NGINX["Nginx Reverse-Proxy<br/>HTTPS 443"]:::ingress
        FRONTEND["Frontend SPA<br/>TypeScript/JS"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        BACKEND["Backend API<br/>Node.js (Express)<br/>HTTPS 8443"]:::backend
    end

    %% Service Layer
    subgraph "Service Layer"
        DDNS["ddnsserver<br/>HTTP 8001"]:::service
        SSH["sshserver<br/>TCP/SSH 22"]:::service
        HIMHIP["himhip<br/>HTTP 8003"]:::service
        VPN["vpn<br/>UDP/TCP 1194"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        MARIADB["MariaDB<br/>3306"]:::db
        INFLUXDB["InfluxDB<br/>8086"]:::db
        REDIS["Redis<br/>6379"]:::db
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ACME["Let's Encrypt ACME"]:::external
        DNSPROV["DNS Providers API"]:::external
        IPLOC["IP-Location Services"]:::external
    end

    %% Docker Compose Boundary
    subgraph "Docker Compose" 
        direction TB
        NGINX
        FRONTEND
        BACKEND
        DDNS
        SSH
        HIMHIP
        VPN
    end

    %% Client
    CLIENT["Browser Client"]:::external

    %% Interactions
    CLIENT -->|HTTPS| NGINX
    NGINX -->|serves /| FRONTEND
    NGINX -->|proxy /api| BACKEND
    BACKEND -->|CRUD| MARIADB
    BACKEND -->|TS Read/Write| INFLUXDB
    BACKEND -->|Cache/PubSub| REDIS
    BACKEND -->|HTTP Calls| DDNS
    BACKEND -->|SSH Commands| SSH
    BACKEND -->|HTTP Calls| HIMHIP
    BACKEND -->|VPN Management| VPN
    BACKEND -->|ACME API| ACME
    BACKEND -->|DNS API| DNSPROV
    BACKEND -->|IP Lookup| IPLOC
    NGINX -->|proxy to user upstreams| CLIENT

    %% Click Events
    click NGINX "https://github.com/stefanwerfling/flyingfish/tree/main/nginx/"
    click FRONTEND "https://github.com/stefanwerfling/flyingfish/tree/main/frontend/"
    click BACKEND "https://github.com/stefanwerfling/flyingfish/tree/main/backend/"
    click DDNS "https://github.com/stefanwerfling/flyingfish/tree/main/ddnsserver/"
    click SSH "https://github.com/stefanwerfling/flyingfish/tree/main/sshserver/"
    click HIMHIP "https://github.com/stefanwerfling/flyingfish/tree/main/himhip/"
    click VPN "https://github.com/stefanwerfling/flyingfish/tree/main/vpn/"
    click MARIADB "https://github.com/stefanwerfling/flyingfish/tree/main/core/"
    click REDIS "https://github.com/stefanwerfling/flyingfish/tree/main/core/"
    click INFLUXDB "https://github.com/stefanwerfling/flyingfish/tree/main/core/"
    click ACME "https://github.com/stefanwerfling/flyingfish/tree/main/schemas/"
    click DNSPROV "https://github.com/stefanwerfling/flyingfish/tree/main/schemas/"
    click IPLOC "https://github.com/stefanwerfling/flyingfish/tree/main/schemas/"

    %% Styles
    classDef ingress fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#DFFFD0,stroke:#22863a,color:#22863a
    classDef service fill:#DFFFD0,stroke:#22863a,color:#22863a
    classDef db fill:#FFE0A0,stroke:#bf8700,color:#bf8700
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d
```
