# th0th/poeticmetric architecture

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

- Interactive diagram: https://gitdiagram.com/th0th/poeticmetric
- Repository: https://github.com/th0th/poeticmetric

## Overview

##### Project Type & Purpose
- PoeticMetric is an open-source, privacy-first website analytics tool. It replaces traditional analytics (like Google Analytics) with a self-hosted alternative that does not track personal data or use cookies.
- The project is a full-stack application comprising both a frontend (built with modern JavaScript/TypeScript frameworks) and a backend (written in Go), with supporting Docker configurations and scripts for self-hosting.

##### File Structure Analysis
- Two top-level directories: “frontend” and “backend.”
– The “frontend” directory contains pages, components, hooks, contexts, and documentation for building the user interface. It uses Next.js (as seen in the pages, next.config.js, and TypeScript types) to deliver the web app.
– The “backend” directory is structured into several submodules organized with commands (like “migrator,” “restapi,” “worker,” “scheduler”) and a rich “pkg” folder. This indicates a robust backend providing REST endpoints, background jobs (workers, schedulers), email templating, database migrations for both Postgres and ClickHouse, and integration with external services.
- Additional directories and files (e.g., Dockerfiles, docker-compose.yaml, self-hosted configurations, CI workflows) show that containerization, deployment automation, and testing are key parts of the project.

##### Key Architectural Components
a. Frontend:
- UI Layer built with React/Next.js, containing multiple component folders (like “Home”, “BlogPage”, “SiteReports”, “Team”) and contexts (e.g., AuthContext, LayoutContext) to manage state.
- Static assets, documents, and user-facing pages.
b. Backend:
- REST API: Organized under backend/cmd/restapi and further subdivided in backend/pkg/restapi with modules for users, organizations, sites, events, and site reports.
- Services and business logic: Separated by domain (site, user, organization, reports, events) to handle core functionality.
- Background Jobs / Workers: Commands like “worker” and “scheduler” to process asynchronous tasks (such as sending email notifications, processing events, and handling trial periods).
- Database Migrations & Data Layer: Migrations for both PostgreSQL and ClickHouse suggest dual-database integration for potentially transactional data and analytical workload.
- Email & Notifications: Email templates and a module for managing email sending and notifications.
- External Integrations: Modules and packages for Stripe (billing), Google (OAuth, Search Console), Mailbluster, RabbitMQ (for message queuing), Redis, and Sentry for error reporting.
c. Infrastructure:
- Docker & Self-hosting: Dockerfile(s) in both “frontend” and “backend”, docker-compose.yaml, and a self-hosted directory indicate containerized deployment.
- CI/CD workflows in the “.github” folder for testing, publishing, and deploying.

- Under Frontend, add subcomponents:
– Pages & Components (e.g., user authentication, site reporting dashboards, blog, settings)
– Contexts/Hooks for state management (auth, layout, reports, etc.)
– REST API Server: Covering endpoints for users, organizations, sites, events, and reports.
– Background Services: Worker processes, scheduler, and migrator modules.
– Data Layer: Illustrate relational databases such as PostgreSQL and analytical databases like ClickHouse.
– Integration Services: Email (with templates), third-party integrations (Stripe for billing, Google OAuth/Search Console, Mailbluster), RabbitMQ/Redis for caching and messaging.
– Environment & Configuration Management: Docker orchestration, environment files, CI configurations.
– Frontend communicates with the Backend REST API.
– Backend interacts with Databases, External Services (e.g., Stripe, Google), and background job queues.

##### Architectural Patterns & Design Principles
- Separation of concerns: Clear division between presentation (Frontend) and business logic/services (Backend).
- Modular design: The backend is further broken into organized packages (e.g., restapi, service, worker) for maintainability and scalability.
- Containerization & self-hosting: Emphasize the role of Docker and orchestration in deploying the application.
- Event-driven processes: Background workers and schedulers imply asynchronous processing.
- API-first approach: REST API endpoints facilitate frontend-backend communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Section
    subgraph "Frontend Layer"
        F1["Frontend (Next.js UI)"]:::frontend
    end

    %% Backend Section
    subgraph "Backend Layer"
        subgraph "REST API"
            API1["REST API Entrypoint"]:::backend
            API2["REST API Endpoints"]:::backend
        end
        subgraph "Data Layer"
            DB1["PostgreSQL Migrations"]:::database
            DB2["ClickHouse Migrations"]:::database
            DB3["Data Access & Integration"]:::database
        end
        subgraph "Background Jobs"
            W1["Worker Command"]:::backend
            WS["Worker Service"]:::backend
            S1["Scheduler Command"]:::backend
        end
        subgraph "Email & Notifications"
            EM1["Email Service"]:::backend
            EM2["Email Templates"]:::backend
        end
        subgraph "External Integrations"
            EX1["Stripe Integration"]:::integration
            EX2["External Env Config"]:::integration
            EX3["Mailbluster Integration"]:::integration
        end
    end

    %% Infrastructure Section
    subgraph "Infrastructure & Containerization"
        INF1["Frontend Dockerfile"]:::infra
        INF2["Backend Dockerfile"]:::infra
        INF3["docker-compose.yaml"]:::infra
        INF4["Self-hosted Config"]:::infra
        INF5["CI/CD (GitHub Actions)"]:::infra
    end

    %% Data Flow Connections
    F1 -->|"calls"| API1
    API1 -->|"routesTo"| API2
    API2 -->|"dbCalls"| DB3
    DB3 -->|"migrates via"| DB1
    DB3 -->|"migrates via"| DB2
    API2 -->|"triggers"| WS
    WS -->|"processes jobs"| W1
    WS -->|"schedules tasks"| S1
    WS -->|"sendsEmails"| EM1
    API2 -->|"invokes"| EX1
    API2 -->|"invokes"| EX2
    API2 -->|"invokes"| EX3

    %% Infrastructure Relationships
    INF5 -->|"builds"| INF1
    INF5 -->|"builds"| INF2
    INF5 -->|"orchestrates"| INF3
    INF3 -->|"deploys"| F1
    INF3 -->|"deploys"| API1
    INF3 -->|"deploys"| WS

    %% Classes
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef database fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef integration fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events
    click F1 "https://github.com/th0th/poeticmetric/tree/main/frontend"
    click API1 "https://github.com/th0th/poeticmetric/tree/main/backend/cmd/restapi"
    click API2 "https://github.com/th0th/poeticmetric/tree/main/backend/pkg/restapi"
    click DB1 "https://github.com/th0th/poeticmetric/tree/main/backend/migrations/postgres"
    click DB2 "https://github.com/th0th/poeticmetric/tree/main/backend/migrations/clickhouse"
    click DB3 "https://github.com/th0th/poeticmetric/tree/main/backend/pkg/depot"
    click W1 "https://github.com/th0th/poeticmetric/tree/main/backend/cmd/worker"
    click S1 "https://github.com/th0th/poeticmetric/tree/main/backend/cmd/scheduler"
    click WS "https://github.com/th0th/poeticmetric/tree/main/backend/pkg/worker"
    click EM1 "https://github.com/th0th/poeticmetric/tree/main/backend/pkg/email"
    click EM2 "https://github.com/th0th/poeticmetric/tree/main/backend/assets/email_templates"
    click EX1 "https://github.com/th0th/poeticmetric/tree/main/backend/pkg/restapi/stripe"
    click EX2 "https://github.com/th0th/poeticmetric/tree/main/backend/pkg/env"
    click EX3 "https://github.com/th0th/poeticmetric/tree/main/backend/pkg/mailbluster"
    click INF1 "https://github.com/th0th/poeticmetric/tree/main/frontend/Dockerfile"
    click INF2 "https://github.com/th0th/poeticmetric/tree/main/backend/Dockerfile"
    click INF3 "https://github.com/th0th/poeticmetric/blob/main/docker-compose.yaml"
    click INF4 "https://github.com/th0th/poeticmetric/tree/main/self-hosted"
    click INF5 "https://github.com/th0th/poeticmetric/blob/main/.github"
```
