# cipherdothost/pkgdex architecture

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

- Interactive diagram: https://gitdiagram.com/cipherdothost/pkgdex
- Repository: https://github.com/cipherdothost/pkgdex

## Overview

##### Main components
- Application Entry Point and Core Logic:
- The Go entry point (main.go) along with the core application logic in internal/app (start, stop, usage) forms the heartbeat of the system.
- Configuration Management:
- The internal/config package, along with the config directory (which contains example configurations, nginx and systemd settings, and an apparmor profile), manages system configuration and deployment flexibility.
- Web Server & Request Handling:
- The internal/server package contains various HTTP handlers (in internal/server/handler) that address routes including downloads, feeds, health checks, package-specific pages, privacy, search, sitemap, and static file serving.
- Middleware components (authorization, CSP) under internal/server/middleware.
- Database and Repository:
- The internal/database and internal/repository packages handle persistent storage for package metadata, download statistics, and possibly other metrics.
- Search and Indexing:
- The internal/search package and internal/pagination support the full-text search across packages.
- Additional Features:
- The internal/rss package deals with RSS feed generation for updates.
- The internal/sitemap and static assets (templates, SCSS files, images) provide sitemap generation and the user-facing frontend.
- The internal/wayback integration supports linking to archived pages via the Wayback Machine.
- Modules such as internal/meta, internal/metric, and internal/version add metadata management, performance/usage metrics, and version handling.

##### Relationships and Interactions
- Start from an external client (e.g., a web browser) that communicates with a reverse proxy or load balancer (configured via the provided nginx settings in config/nginx).
- The reverse proxy forwards requests to the Pkgdex server (running the Go application).
- The server’s HTTP handlers (grouped under the internal/server/handler folder) serve various endpoints:
- Static content served from the “static” folder (HTML templates, CSS/SCSS, images).
- API endpoints for search (internal/search) and package views.
- Endpoint(s) for RSS feed, sitemap, and health check requests.
- Business logic components, such as the configuration loader (from internal/config), initialize the system.
- For data persistence, the server communicates with the database and repository layers (internal/database, internal/repository) for storing/retrieving package metadata and download stats.
- Auxiliary services (Wayback integration, RSS, metrics) interact with external systems or process internal data to enrich the functionality.

##### Architectural Patterns and Design Principles
- Modular design: The project is segmented into clear responsibilities (configuration, HTTP serving, data access, search, and external integrations).
- Extensibility: Show how components such as search, metrics, and third-party integrations (RSS, Wayback) can evolve separately.
- Testability: Highlight the inclusion of dedicated test helper modules and test data (internal/testhelper, testdata) that support unit and integration tests.

##### Relevant Technologies and Frameworks
- Written in Go (Go modules are listed in go.mod and go.sum).
- Uses make for building the project.
- Includes static assets managed via package.json/package-lock.json, suggesting some Node-based build steps for frontend assets.
- Deployment configurations exist for systemd, nginx reverse proxy, and apparmor in the config directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    Client["Client (Web Browser)"]:::infra
    NGINX["NGINX/Reverse Proxy (config/nginx)"]:::infra
    WMachine["Wayback Machine"]:::infra

    %% Application Layer
    App["Pkgdex Go Application"]:::app

    %% External Connections
    Client -->|"HTTP Request"| NGINX
    NGINX -->|"Forwards Request"| App

    subgraph "Pkgdex Go Application"
        direction LR
        
        %% Core Components
        CoreSub["Core Components"]:::coreGroup
        Core1["Go Entry Point (main.go)"]:::core
        Core2["Core Logic (internal/app)"]:::core
        
        CoreSub --- Core1
        CoreSub --- Core2

        %% Configuration Management
        ConfigSub["Configuration"]:::configGroup
        Config1["Config Loader (internal/config)"]:::config
        Config2["Config Files (config)"]:::config
        
        ConfigSub --- Config1
        ConfigSub --- Config2

        %% Web Server & Request Handling
        ServerSub["Web Server"]:::serverGroup
        Server1["HTTP Server (internal/server)"]:::server
        Server2["HTTP Handlers (internal/server/handler)"]:::server
        Server3["Middleware (internal/server/middleware)"]:::server
        
        ServerSub --- Server1
        Server1 --- Server2
        Server1 --- Server3

        %% Data Persistence
        DBSub["Data Layer"]:::dbGroup
        DB1["Database (internal/database)"]:::db
        DB2["Repository (internal/repository)"]:::db
        
        DBSub --- DB1
        DBSub --- DB2

        %% Search and Indexing
        SearchSub["Search & Indexing"]:::searchGroup
        Search1["Search Engine (internal/search)"]:::search
        Search2["Pagination (internal/pagination)"]:::search
        
        SearchSub --- Search1
        SearchSub --- Search2

        %% Additional Features
        FeatureSub["Additional Features"]:::featureGroup
        Feature1["RSS Feed (internal/rss)"]:::feature
        Feature2["Sitemap (internal/sitemap)"]:::feature
        Feature3["Static Content (static)"]:::feature
        Feature31["Templates (static/templates)"]:::feature
        Feature4["Wayback Integration (internal/wayback)"]:::feature
        
        FeatureSub --- Feature1
        FeatureSub --- Feature2
        FeatureSub --- Feature3
        FeatureSub --- Feature31
        FeatureSub --- Feature4

        %% Metadata, Metrics, Versioning
        MetricsSub["Metadata & Metrics"]:::metricsGroup
        Metrics1["Metadata (internal/meta)"]:::metrics
        Metrics2["Metrics (internal/metric)"]:::metrics
        Metrics3["Versioning (internal/version)"]:::metrics
        
        MetricsSub --- Metrics1
        MetricsSub --- Metrics2
        MetricsSub --- Metrics3

        %% Test Helpers
        TestNode["Test Helpers (internal/testhelper)"]:::test

        %% Interactions between components
        %% Core initialization links to Configuration and Web Server
        CoreSub -->|"loads config"| ConfigSub
        CoreSub -->|"starts server"| ServerSub

        %% HTTP Handlers interact with Data, Search, and Features
        Server2 -->|"queries"| DBSub
        Server2 -->|"queries"| SearchSub
        Server2 -->|"generates"| FeatureSub
        Server2 -->|"collects"| MetricsSub

        %% Middleware supports HTTP Handlers
        Server3 --> Server2

        %% Wayback Integration external dependency
        Feature4 -->|"calls"| WMachine

        %% Optional: Test Helpers used alongside core logic
        CoreSub --- TestNode
    end

    %% Click Events
    click Core1 "https://github.com/cipherdothost/pkgdex/blob/trunk/main.go"
    click Core2 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/app/"
    click Config1 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/config/"
    click Config2 "https://github.com/cipherdothost/pkgdex/tree/trunk/config/"
    click Server1 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/server/"
    click Server2 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/server/handler/"
    click Server3 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/server/middleware/"
    click DB1 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/database/"
    click DB2 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/repository/"
    click Search1 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/search/"
    click Search2 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/pagination/"
    click Feature1 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/rss/"
    click Feature2 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/sitemap/"
    click Feature3 "https://github.com/cipherdothost/pkgdex/tree/trunk/static/"
    click Feature31 "https://github.com/cipherdothost/pkgdex/tree/trunk/static/templates/"
    click Feature4 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/wayback/"
    click Metrics1 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/meta/"
    click Metrics2 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/metric/"
    click Metrics3 "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/version/"
    click TestNode "https://github.com/cipherdothost/pkgdex/tree/trunk/internal/testhelper/"

    %% Styles
    classDef infra fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef app fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef core fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef config fill:#ffa07a,stroke:#000,stroke-width:2px;
    classDef server fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef db fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef search fill:#e6e6fa,stroke:#000,stroke-width:2px;
    classDef feature fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef metrics fill:#deb887,stroke:#000,stroke-width:2px;
    classDef test fill:#dcdcdc,stroke:#000,stroke-width:2px;
    
    %% Group styling (subgraph labels are not directly styleable, but groups use nodes' classes)
    class Client,NGINX,WMachine infra;
    class App app;
    class Core1,Core2 core;
    class Config1,Config2 config;
    class Server1,Server2,Server3 server;
    class DB1,DB2 db;
    class Search1,Search2 search;
    class Feature1,Feature2,Feature3,Feature31,Feature4 feature;
    class Metrics1,Metrics2,Metrics3 metrics;
    class TestNode test;
```
