# rekryt/iplist architecture

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

- Interactive diagram: https://gitdiagram.com/rekryt/iplist
- Repository: https://github.com/rekryt/iplist

## Overview

##### Project Type and Purpose
- This is a full-stack monorepo that combines:
- A backend asynchronous PHP web service (AMPHP + Linux CLI tools) for collecting/updating IP addresses and CIDR zones, exposing a REST-style “format” API.
- A static frontend (Nuxt.js + Vuetify) that builds a documentation/UI site.
- Purpose: load JSON configurations of domains, fetch & compute IP/CIDR lists via DNS/whois/ipcalc tasks, cache results to disk, and serve them in multiple text/JSON/script formats.

##### File Structure Analysis
- Top-level:
- Docker integration (.docker/, Dockerfile, docker-compose.yml, .env)
- Backend entrypoint (index.php), composer.json, config/… JSON domain configs, storage/… JSON cache files.
- frontend/ – a standalone Nuxt.js project (package.json, nuxt.config.ts, pages/, components/, stores/, public/_nuxt build).
- public/ – built static assets (generated by frontend build).
- src/ – backend source following a layered (“hexagonal”) architecture:
– App layer (Controllers, Services, Templates)
– Domain layer (Entity, Factory, Helper)
– Infrastructure layer (API server & handlers, Storage adapters, Task runners)
- Patterns:
- Hexagonal/Ports & Adapters (Infrastructure API & Storage adapters)
- Layered MVC‐style for HTTP controllers → services → domain → storage
- Docker Compose for orchestration

##### Key Architecture Insights from README
- Asynchronous PHP HTTP server powered by AMPHP and “index.php” as the entrypoint.
- Uses Linux tools (whois, ipcalc) via ShellTask adapter.
- Config JSON files (config/<group>/<portal>.json) drive domain lists, DNS servers, external URLs.
- Outputs in multiple formats via dedicated Controller classes (e.g., Mikrotik, ipset, comma).
- Configurable via environment (.env) and Docker Compose.

a. Main Components
- Client/browser – accesses the static frontend or calls the API endpoints directly.
- Frontend layer – Nuxt.js static site (built assets served from public/_nuxt or a CDN).
- Reverse proxy (optional NginxProxyManager) – routes HTTP 80/443 to backend container.
- Backend container – PHP 8.1+ AMPHP HTTP server (index.php → Infrastructure/API/Server).
- Router & Request Handlers – HTTPErrorHandler, HTTPHandler dispatch to App\Controllers.
- Controller layer – one Controller per format (e.g., JsonController, MikrotikController) implementing ControllerInterface.
- Service layer – IPListService orchestrates data gathering, applies Domain logic.
- Domain layer – Entities (Site), Factories (SiteFactory), Helpers (DNSHelper, IP4Helper, IP6Helper).
- Infrastructure Adapters:
– Task runner (ShellTask) for whois/ipcalc/dnsutils calls
– Storage adapters (CIDRStorage, IconsStorage) reading/writing storage/*.json
- Config loader – reads config/*.json into Domain factories
- External systems – Public DNS servers, external data URLs, Linux CLI tools
- Persistent volume – storage/ directory mounted in container

b. Relationships & Data Flow
1. Client → (optional) Reverse Proxy → Backend HTTP server
2. HTTP server → Request Handlers → Controller
3. Controller → IPListService →
- Config loader → Domain Factory → creates Site entity
- Domain Helpers → fetch DNS records via ShellTask → whois/ipcalc
- Storage adapters → read/write JSON cache
4. Service → collated data → chosen Controller → Template → HTTP response
5. Client receives formatted IP/CIDR list or static docs (frontend)

c. Architectural Patterns
- Hexagonal (“ports & adapters”) separating core domain logic from I/O (HTTP, CLI tasks, file storage)
- Layered approach: Infrastructure → Application → Domain → Infrastructure
- Single‐responsibility Controllers per output format
- Docker Compose microservices style (frontend build vs. backend service)

d. Key Technologies & Libraries
- PHP 8.1+, AMPHP (async HTTP server)
- Composer packages
- Linux utilities: whois, dnsutils, ipcalc
- JSON config & cache storage
- Nuxt.js + Vuetify (frontend)
- Docker, Docker Compose (.env, networks, volumes)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and Network
    Client["Browser / CLI"]:::client
    subgraph "Reverse Proxy / Load Balancer"
        Proxy["NginxProxyManager"]:::network
    end

    %% Frontend
    subgraph "Frontend Service"
        FEProject["Nuxt.js Frontend"]:::frontend
        FEBuilt["Built Assets (public/_nuxt)"]:::frontend
    end

    %% Backend
    subgraph "Backend Service (PHP AMPHP)"
        Entrypoint["index.php"]:::backend
        APIServer["AMPHP HTTP Server"]:::backend

        subgraph "Request Handling"
            HTTPHandler["HTTPHandler"]:::backend
            HTTPErrorHandler["HTTPErrorHandler"]:::backend
            Handler["Handler"]:::backend
        end

        subgraph "Controllers"
            JsonController["JsonController"]:::controller
            MikrotikController["MikrotikController"]:::controller
            CommaController["CommaController"]:::controller
            AbstractController["AbstractIPListController"]:::controller
        end

        Service["IPListService"]:::service

        subgraph "Domain Layer"
            SiteEntity["Site Entity"]:::domain
            SiteFactory["SiteFactory"]:::domain
            DNSHelper["DNSHelper"]:::domain
            IP4Helper["IP4Helper"]:::domain
            IP6Helper["IP6Helper"]:::domain
        end

        subgraph "Infrastructure & Adapters"
            ShellTask["ShellTask Adapter"]:::infrastructure

            subgraph "Storage Adapters"
                StorageInterface["StorageInterface"]:::storage
                CIDRStorage["CIDRStorage"]:::storage
                IconsStorage["IconsStorage"]:::storage
            end
        end

        Entrypoint --> APIServer
        APIServer --> HTTPHandler
        HTTPHandler --> Controllers
        Controllers --> Service
        Service --> SiteFactory
        Service --> DNSHelper
        Service --> IP4Helper
        Service --> IP6Helper
        Service --> ShellTask
        Service --> StorageInterface
        StorageInterface --> CIDRStorage
        StorageInterface --> IconsStorage
        SiteFactory --> SiteEntity
    end

    %% Configuration & Storage
    Config["Config Files (config/*.json)"]:::config
    Volume["Persistent Volume (storage/)"]:::storage
    Env[".env & Docker Compose"]:::infra
    Composer["composer.json"]:::config
    Functions["Global Helpers (functions.php)"]:::infrastructure

    %% External Dependencies
    DNS["Public DNS Servers"]:::external
    CLI["Linux CLI Tools (whois/dnsutils/ipcalc)"]:::external
    ExtURL["External URLs"]:::external

    %% Data Flows
    Client --> Proxy
    Proxy --> Entrypoint
    Client --> FEProject
    Client -->|Fetch Static Docs| FEBuilt

    Service --> Config
    Service --> Volume
    Service --> Env
    Service --> Composer
    Service --> Functions

    DNSHelper --> DNS
    ShellTask --> CLI
    Service --> ExtURL

    %% Click Events
    click Entrypoint "https://github.com/rekryt/iplist/blob/master/index.php"
    click APIServer "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/API/Server.php"
    click HTTPHandler "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/API/Handler/HTTPHandler.php"
    click HTTPErrorHandler "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/API/Handler/HTTPErrorHandler.php"
    click Handler "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/API/Handler/Handler.php"
    click JsonController "https://github.com/rekryt/iplist/blob/master/src/App/Controller/JsonController.php"
    click MikrotikController "https://github.com/rekryt/iplist/blob/master/src/App/Controller/MikrotikController.php"
    click CommaController "https://github.com/rekryt/iplist/blob/master/src/App/Controller/CommaController.php"
    click AbstractController "https://github.com/rekryt/iplist/blob/master/src/App/Controller/AbstractIPListController.php"
    click Service "https://github.com/rekryt/iplist/blob/master/src/App/Service/IPListService.php"
    click SiteEntity "https://github.com/rekryt/iplist/blob/master/src/Domain/Entity/Site.php"
    click SiteFactory "https://github.com/rekryt/iplist/blob/master/src/Domain/Factory/SiteFactory.php"
    click DNSHelper "https://github.com/rekryt/iplist/blob/master/src/Domain/Helper/DNSHelper.php"
    click IP4Helper "https://github.com/rekryt/iplist/blob/master/src/Domain/Helper/IP4Helper.php"
    click IP6Helper "https://github.com/rekryt/iplist/blob/master/src/Domain/Helper/IP6Helper.php"
    click ShellTask "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/Task/ShellTask.php"
    click CIDRStorage "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/Storage/CIDRStorage.php"
    click IconsStorage "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/Storage/IconsStorage.php"
    click StorageInterface "https://github.com/rekryt/iplist/blob/master/src/Infrastructure/Storage/StorageInterface.php"
    click Config "https://github.com/rekryt/iplist/tree/master/config/"
    click Volume "https://github.com/rekryt/iplist/tree/master/storage/"
    click FEProject "https://github.com/rekryt/iplist/tree/master/frontend/"
    click FEBuilt "https://github.com/rekryt/iplist/tree/master/public/_nuxt/"
    click Env "https://github.com/rekryt/iplist/blob/master/docker-compose.yml"
    click Composer "https://github.com/rekryt/iplist/blob/master/composer.json"
    click Functions "https://github.com/rekryt/iplist/blob/master/src/functions.php"

    %% Styles
    classDef client fill:#FFD580,stroke:#333,stroke-width:1px
    classDef network fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef frontend fill:#F5B7B1,stroke:#333,stroke-width:1px
    classDef backend fill:#A9DFBF,stroke:#333,stroke-width:1px
    classDef controller fill:#82E0AA,stroke:#333,stroke-width:1px
    classDef service fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef domain fill:#BB8FCE,stroke:#333,stroke-width:1px
    classDef infrastructure fill:#D5DBDB,stroke:#333,stroke-width:1px
    classDef storage fill:#F1948A,stroke:#333,stroke-width:1px
    classDef config fill:#7FB3D5,stroke:#333,stroke-width:1px
    classDef infra fill:#D7BDE2,stroke:#333,stroke-width:1px
    classDef external fill:#F7DC6F,stroke:#333,stroke-width:1px
```
