# dahlia/hackerspub architecture

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

## Overview

##### Main Components
- Frontend/UI:
- Components Folder: Contains reusable UI elements (e.g., Button, Input, Profile, etc.).
- Islands Folder: Implements interactive or client-side rendered components (e.g., Editor, Composer, Timestamp) which likely get hydrated on the client via the Fresh framework.
- Routes Folder: Houses pages and route-specific components (including dynamic routing for user profiles and posts) and special pages (404, sitemaps, etc.). This is the entry point for client requests.

- Backend/API:
- Routes (subfolders “api”, “sign”, “admin”, etc.): Provide RESTful APIs and server-side functionality (user authentication, post management, search, mentions, etc.).
- Federation Folder: Contains modules that implement the ActivityPub functionality (actors, collections, inbox, federation interaction, nodeinfo, etc.) enabling communication with external fediverse nodes.
- Models: Contains business logic and domain models for entities like account, actor, post, article, etc. Also includes tests for validation.
- Utilities: Files like “logging.ts”, “sentry.ts”, “drive.ts” and “email.ts” handle operational tasks such as logging, error tracking, file handling, or email notifications.
- Main.ts: Acts as the server entry point (bootstrapping the web server and connecting routes/middleware).

- Database & Data Persistence:
- Drizzle Folder and drizzle.config.ts: Hold SQL migration files and configuration for Drizzle ORM, which manages schema definitions, migrations, and model interactions.
- db.ts: Likely a central database helper that provides connections or data access methods.
- kv.ts: May act as a key–value store for cache or session storage.

- Development & Deployment:
- Dockerfile, Dockerfile.dev, docker-compose.yml: Provide environment containerization setups for development and production.
- Configuration Files: deno.json, .env.sample, and CI/CD pipelines under .github/workflows.
- Miscellaneous: A “mise.toml” and other configuration files that coordinate deployment or environment-specific settings.

##### Relationships and Interactions
- Data Flow and User Requests:
- Users (via a web browser) interact with the frontend (served via routes) and receive interactive components (islands) and static assets.
- Backend API endpoints (under routes/api, sign, admin) handle business logic, authentication, and data manipulation.

- Database Interactions:
- The backend leverages Drizzle ORM for managing schema migrations and database queries, with the “drizzle” folder indicating versioned SQL migrations.

- Federated Communication:
- The “federation” modules manage outbound and inbound ActivityPub requests (sending/receiving posts, follow notifications, etc.), functioning as a bridge between local user content and the wider fediverse.

- Configuration and Deployment:
- Containerization is provided via Docker files and docker-compose, ensuring that the development and production environments are isolated and reproducible.

- Logging and Monitoring:
- Logging modules, Sentry integration, and optional key/value caches provide observability into the system.

##### Architectural Patterns and Technologies
- Separation of Concerns: Clear division between front-end (UI components, islands, routes), back-end API (routes, models, federation, utilities), and the database layer.
- Modular Design: Each folder (components, islands, routes, federation, models) is self-contained, making the components easy to update or replace.
- Federated Architecture: Unique integrations for ActivityPub carving a pathway between this server and other fediverse nodes.
- Utilization of Deno: Leveraging modern TypeScript, built-in web server capabilities, and the ecosystem around Fresh.

## Diagram (Mermaid)

```mermaid
flowchart TD
    B["User's Browser"]:::external

    subgraph "Frontend"
        FE_Routes["Routes & Pages (routes)"]:::frontend
        FE_Islands["Islands (Interactive) (islands)"]:::frontend
        FE_Components["Reusable Components (components)"]:::frontend
        FE_Static["Static Assets & Fonts (static)"]:::frontend
    end

    subgraph "Backend/API"
        API["API Endpoints (routes/api, routes/sign, routes/admin)"]:::backend
        Federation["Federation Modules (federation)"]:::backend
        Models["Domain Models (models)"]:::backend
        Main["Server Entry (main.ts)"]:::backend
        subgraph "Utilities"
            U_Logging["Logging (logging.ts)"]:::backend
            U_Sentry["Sentry (sentry.ts)"]:::backend
            U_Drive["Drive (drive.ts)"]:::backend
            U_Email["Email (email.ts)"]:::backend
        end
    end

    subgraph "Database"
        DB_ORM["Drizzle ORM & Migrations (drizzle, drizzle.config.ts)"]:::database
        DB_Helper["Database Helper (db.ts)"]:::database
        DB_KV["KV Store (kv.ts)"]:::database
    end

    subgraph "Deployment & Configuration"
        D_Dockerfile["Dockerfile"]:::deployment
        D_DockerfileDev["Dockerfile.dev"]:::deployment
        D_DockerCompose["docker-compose.yml"]:::deployment
        D_Env[".env.sample"]:::deployment
        D_Deno["deno.json"]:::deployment
        D_Mise["mise.toml"]:::deployment
        D_Workflows[".github/workflows"]:::deployment
    end

    %% Connections
    B -->|"accesses"| FE_Routes
    FE_Routes -->|"renders"| FE_Components
    FE_Routes -->|"hydrates"| FE_Islands
    FE_Routes -->|"serves"| FE_Static
    FE_Routes -->|"calls"| API
    API -->|"processes"| Models
    API -->|"triggers"| Federation
    API -->|"bootstraps"| Main
    Main -->|"utilizes"| U_Logging
    Main -->|"utilizes"| U_Sentry
    Main -->|"utilizes"| U_Drive
    Main -->|"utilizes"| U_Email
    Models -->|"interacts"| DB_ORM
    Main -->|"connects to"| DB_Helper
    DB_ORM -->|"migrates to"| DB_Helper
    DB_ORM -->|"caches with"| DB_KV
    Federation -->|"sends/receives"| Fed["External Fediverse"]:::external
    D_Dockerfile -->|"deploys"| Main
    D_DockerfileDev -->|"deploys"| Main
    D_DockerCompose -->|"deploys"| Main
    D_Env -->|"configures"| Main
    D_Deno -->|"configures"| Main
    D_Mise -->|"configures"| Main
    D_Workflows -->|"automates"| Main

    %% Click Events
    click FE_Components "https://github.com/dahlia/hackerspub/tree/main/components"
    click FE_Islands "https://github.com/dahlia/hackerspub/tree/main/islands"
    click FE_Routes "https://github.com/dahlia/hackerspub/tree/main/routes"
    click FE_Static "https://github.com/dahlia/hackerspub/tree/main/static"
    click API "https://github.com/dahlia/hackerspub/tree/main/routes/api"
    click Federation "https://github.com/dahlia/hackerspub/tree/main/federation"
    click Models "https://github.com/dahlia/hackerspub/tree/main/models"
    click U_Logging "https://github.com/dahlia/hackerspub/blob/main/logging.ts"
    click U_Sentry "https://github.com/dahlia/hackerspub/blob/main/sentry.ts"
    click U_Drive "https://github.com/dahlia/hackerspub/blob/main/drive.ts"
    click U_Email "https://github.com/dahlia/hackerspub/blob/main/email.ts"
    click Main "https://github.com/dahlia/hackerspub/blob/main/main.ts"
    click DB_ORM "https://github.com/dahlia/hackerspub/tree/main/drizzle"
    click DB_ORM "https://github.com/dahlia/hackerspub/blob/main/drizzle.config.ts"
    click DB_Helper "https://github.com/dahlia/hackerspub/blob/main/db.ts"
    click DB_KV "https://github.com/dahlia/hackerspub/blob/main/kv.ts"
    click D_Dockerfile "https://github.com/dahlia/hackerspub/tree/main/Dockerfile"
    click D_DockerfileDev "https://github.com/dahlia/hackerspub/blob/main/Dockerfile.dev"
    click D_DockerCompose "https://github.com/dahlia/hackerspub/blob/main/docker-compose.yml"
    click D_Env "https://github.com/dahlia/hackerspub/blob/main/.env.sample"
    click D_Deno "https://github.com/dahlia/hackerspub/blob/main/deno.json"
    click D_Mise "https://github.com/dahlia/hackerspub/blob/main/mise.toml"
    click D_Workflows "https://github.com/dahlia/hackerspub/tree/main/.github/workflows"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#bfb,stroke:#333,stroke-width:2px;
    classDef database fill:#ffb,stroke:#333,stroke-width:2px;
    classDef deployment fill:#fdd,stroke:#333,stroke-width:2px;
```
