# bloom42/markdown-ninja architecture

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

- Interactive diagram: https://gitdiagram.com/bloom42/markdown-ninja
- Repository: https://github.com/bloom42/markdown-ninja

## Overview

##### Project type and purpose
- Markdown Ninja is a full-stack, markdown-first CMS/platform to publish websites, blogs, newsletters.
- It comprises:
– A Go-based HTTP API server (cmd/mdninja-server + pkg/server + pkg/services/…)
– A Vue/TypeScript single-page app (“webapp”) served by the Go server
– A CLI tool (cmd/mdninja) for end-users to publish content
– A suite of SDKs (mdninja-go, mdninja-js) for programmatic access
– Auxiliary commands (e.g. ebook generator)

##### File structure
- Top‐level “cmd” directories are entrypoints: CLI, server, ebook converter.
- “pkg/server” implements REST routes, HTTP context and middlewares.
- “pkg/services” contains domain-by-domain logic (contacts, content, emails, events, organizations, store, websites, kernel, site).
- “migrations” holds SQL migration files for the Postgres database.
- “pkg/storage” wraps S3; “pkg/mailer” wraps SES.
- “pkg/worker” provides background job execution.
- “webapp” is the front-end SPA with Vue components, API client, routing and state.
- “themes” holds prebuilt front-end themes (blog, docs) that plug into the webapp.
- “mdninja-go” and “mdninja-js” are language-specific client libraries.

##### README for additional insights
- Purpose: publish Markdown content with a single CLI command or via the web UI.
- Key stack: Go, Vue/TS, Docker, Postgres, S3, SES, Stripe for billing, Scaleway KMS.
- Emphasizes minimal CI/CD and turnkey hosting.

##### Components and their interactions (to represent
a. Clients
– CLI (cmd/mdninja)
– Web SPA (webapp served at /)
– SDKs (mdninja-go, mdninja-js, pingoo-go)
b. API Server
– HTTP router & handlers (pkg/server/api​Routes)
– Middlewares (authentication, logging, CORS, security headers)
– Handlers delegate to “pkg/services/*”
c. Services Layer
– Domain services (contacts, content, emails, events, organizations, store, websites, site, kernel)
– Each service has Repository (DB), business rules, templates (email, HTML)
d. Persistence & Infrastructure
– PostgreSQL database (migrations)
– S3-compatible object storage (assets, images)
– Email service (SES via pkg/mailer/ses)
– Stripe (billing, webhooks)
– KMS for encryption
– Worker process (pkg/worker) for background jobs (email, scheduled publishing, cleanup, etc.)
e. External integrations
– Stripe API
– SES SMTP/REST
– CDN / custom domains

##### Architectural patterns & design principles
- Layered (Clean) architecture:
Presentation → API → Services → Repositories → Data stores
- Hexagonal/Ports & Adapters: services under “pkg/services” depend only on repository interfaces; adapters live in “pkg/services/*/repository” and “pkg/storage”, “pkg/mailer”.
- Single responsibility: each service directory handles one domain.
- Background job queue: worker pulls tasks from the DB or queue table.
- Containerization & IaC: Dockerfiles, devcontainer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        CLI["CLI Tool (cmd/mdninja)"]:::client
        SPA["Web SPA (webapp)"]:::client
        SDKGo["Go SDK (mdninja-go)"]:::client
        SDKJS["JS SDK (mdninja-js)"]:::client
        SDKPingoo["Pingoo-Go SDK (pingoo-go)"]:::client
    end

    %% API Server Layer
    subgraph "API Server" 
        direction TB
        ServerEntrypoint["API Server Entrypoint (cmd/mdninja-server)"]:::server
        Router["HTTP Router & Handlers"]:::server
        Middlewares["Server Middlewares"]:::server
        HTTPUtil["HTTP Context & Utilities"]:::server
    end

    %% Services Layer
    subgraph "Services Layer" 
        direction TB
        Contacts["Contacts Service"]:::service
        Content["Content Service"]:::service
        Emails["Emails Service"]:::service
        Events["Events Service"]:::service
        Orgs["Organizations Service"]:::service
        Store["Store Service"]:::service
        Websites["Websites Service"]:::service
        Site["Public Site Service"]:::service
        Kernel["Core Kernel Service"]:::service
        CertMgr["Certificate Manager"]:::service
    end

    %% Persistence & Infra Layer
    subgraph "Persistence & Infrastructure"
        direction TB
        Postgres["PostgreSQL Database"]:::db
        Migrations["Migrations"]:::db
        S3Storage["S3 Storage"]:::infra
        SESMail["SES Mailer"]:::infra
        ConsoleMail["Console Mailer"]:::infra
        KMS["KMS Integration"]:::infra
        Stripe["Stripe (Billing)"]:::infra
        Worker["Background Worker"]:::worker
        DBX["Database Utilities (dbx)"]:::infra
        JWT["JWT Utilities"]:::infra
    end

    %% External Services
    subgraph "External Integrations"
        direction TB
        StripeAPI["Stripe API"]:::external
        SESAPI["SES SMTP/REST"]:::external
        CDN["CDN / Custom Domains"]:::external
    end

    %% Connections
    CLI -->|HTTPS| ServerEntrypoint
    SPA -->|HTTPS| ServerEntrypoint
    SDKGo -->|HTTPS| ServerEntrypoint
    SDKJS -->|HTTPS| ServerEntrypoint
    SDKPingoo -->|HTTPS| ServerEntrypoint

    ServerEntrypoint --> Router
    Router --> Middlewares
    Middlewares --> HTTPUtil
    HTTPUtil --> Contacts
    HTTPUtil --> Content
    HTTPUtil --> Emails
    HTTPUtil --> Events
    HTTPUtil --> Orgs
    HTTPUtil --> Store
    HTTPUtil --> Websites
    HTTPUtil --> Site
    HTTPUtil --> Kernel
    HTTPUtil --> CertMgr

    Contacts -->|reads/writes| Postgres
    Content -->|reads/writes| Postgres
    Events -->|reads/writes| Postgres
    Orgs -->|reads/writes| Postgres
    Store -->|reads/writes| Postgres
    Websites -->|reads/writes| Postgres
    Site -->|reads/writes| Postgres
    Kernel -->|reads/writes| Postgres
    CertMgr -->|reads/writes| Postgres

    Content -->|stores assets| S3Storage
    Emails -->|sends via| SESMail
    Emails -->|sends fallback| ConsoleMail
    Kernel -->|encrypt/decrypt| KMS
    Store -->|billing| Stripe

    Postgres --> Worker
    Worker --> Contacts
    Worker --> Content
    Worker --> Emails
    Worker --> Events
    Worker --> Orgs
    Worker --> Store
    Worker --> Websites
    Worker --> Site
    Worker --> Kernel
    Worker --> CertMgr

    Stripe -->|webhooks| ServerEntrypoint
    Stripe -->|API calls| Store
    SESMail -->|SMTP/REST| SESAPI
    S3Storage -->|object storage| CDN

    %% Click Events
    click CLI "https://github.com/bloom42/markdown-ninja/tree/main/cmd/mdninja"
    click SPA "https://github.com/bloom42/markdown-ninja/tree/main/webapp"
    click SDKGo "https://github.com/bloom42/markdown-ninja/tree/main/mdninja-go"
    click SDKJS "https://github.com/bloom42/markdown-ninja/tree/main/mdninja-js"
    click SDKPingoo "https://github.com/bloom42/markdown-ninja/tree/main/pingoo-go"
    click ServerEntrypoint "https://github.com/bloom42/markdown-ninja/tree/main/cmd/mdninja-server"
    click Router "https://github.com/bloom42/markdown-ninja/blob/main/pkg/server/api/api_routes.go"
    click Router "https://github.com/bloom42/markdown-ninja/blob/main/pkg/server/routes.go"
    click Middlewares "https://github.com/bloom42/markdown-ninja/tree/main/pkg/server/middlewares"
    click Contacts "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/contacts"
    click Content "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/content"
    click Emails "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/emails"
    click Events "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/events"
    click Orgs "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/organizations"
    click Store "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/store"
    click Websites "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/websites"
    click Site "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/site"
    click Kernel "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/kernel"
    click CertMgr "https://github.com/bloom42/markdown-ninja/tree/main/pkg/services/certmanager"
    click Migrations "https://github.com/bloom42/markdown-ninja/tree/main/migrations"
    click S3Storage "https://github.com/bloom42/markdown-ninja/blob/main/pkg/storage/s3/s3.go"
    click SESMail "https://github.com/bloom42/markdown-ninja/blob/main/pkg/mailer/ses/ses.go"
    click ConsoleMail "https://github.com/bloom42/markdown-ninja/blob/main/pkg/mailer/console/console.go"
    click KMS "https://github.com/bloom42/markdown-ninja/tree/main/pkg/kms"
    click Worker "https://github.com/bloom42/markdown-ninja/blob/main/pkg/worker/worker.go"
    click DBX "https://github.com/bloom42/markdown-ninja/blob/main/pkg/dbx/dbx.go"
    click JWT "https://github.com/bloom42/markdown-ninja/tree/main/pkg/jwt"
    click HTTPUtil "https://github.com/bloom42/markdown-ninja/tree/main/pkg/server/httpctx"
    click HTTPUtil "https://github.com/bloom42/markdown-ninja/tree/main/pkg/server/apiutil"
    click SPA "https://github.com/bloom42/markdown-ninja/blob/main/webapp/webapp.go"
    click EBook "https://github.com/bloom42/markdown-ninja/tree/main/cmd/mdninja-ebook"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef server fill:#D6F5D6,stroke:#228B22,color:#228B22;
    classDef service fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef db fill:#E8E8E8,stroke:#A9A9A9,color:#333333;
    classDef infra fill:#F0F8FF,stroke:#6495ED,color:#0B3D91;
    classDef worker fill:#FFF0F5,stroke:#C71585,color:#C71585;
    classDef external fill:#F5F5F5,stroke:#708090,color:#708090;
```
