Ogen

Ogen is a multi-tenant content operations platform that helps a creator plan, draft, and publish social content end-to-end:

• Plan campaigns and individual posts with AI assistance grounded in your own content bank.
• Draft in a Markdown-first editor backed by an LLM assistant that can search assets, rewrite posts, and produce platform-specific variants.
• Publish automatically to LinkedIn, X, Facebook, Instagram, Threads, and YouTube via the Zernio broker — durable background jobs handle submission, polling, cancellation, and reconciliation, with a per-post audit log capturing every state change.

This repository is the API — a Go 1.26 monolith (Fiber + Bun + PostgreSQL). Its background jobs run in ogen-app/river-service. The React + Vite SPA lives in its own repository, ogen-app/ui, and deploys separately.

Contents

• Architecture
  • System context (C4 level 1)
  • Containers (C4 level 2)
  • The API monolith, up close
• Capabilities
• AI flows (Genkit)
• Infrastructure & deployment
• Development
• Backend development
• Running the full stack with Docker Compose
• Repository skills

---

Architecture

The architecture below is described with the C4 model at levels 1 (System Context) and 2 (Containers). The diagrams are rendered inline as Mermaid so they show up on GitHub; the canonical model is authored as a Structurizr workspace in docs/architecture/workspace.dsl (open it in Structurizr Lite for the full interactive rendering, including the deployment view).

System context (C4 level 1)

Ogen is a single software system that a creator drives through the web app and that an operator administers through Harbor. It depends on a handful of hosted services for language models, publishing, scraping, and email.

C4Context
    title System Context — Ogen

    Person(creator, "Creator / Operator", "Plans campaigns, drafts posts with AI, schedules publishing")
    Person(admin, "Platform Operator", "Manages tenants, secrets, and usage")

    System(ogen, "Ogen", "Plans, drafts, and auto-publishes social content grounded in each tenant's content bank")

    System_Ext(anthropic, "Anthropic Claude API", "Planning, assistants, quality scoring")
    System_Ext(gemini, "Gemini API", "Embeddings, audio transcription, image vision")
    System_Ext(zernio, "Zernio", "Social publishing broker")
    System_Ext(social, "Social platforms", "LinkedIn · X · Facebook · Instagram · Threads · YouTube")
    System_Ext(firecrawl, "Firecrawl", "URL → Markdown scraping")
    System_Ext(resend, "Resend", "Transactional & marketing email")
    System_Ext(sentry, "Sentry", "Error monitoring + OpenTelemetry traces")

    Rel(creator, ogen, "Plans, drafts, schedules", "HTTPS")
    Rel(admin, ogen, "Administers", "HTTPS / gRPC")
    Rel(ogen, anthropic, "Generates content", "HTTPS")
    Rel(ogen, gemini, "Embeds & analyzes assets", "HTTPS")
    Rel(ogen, zernio, "Submits & reconciles posts", "HTTPS")
    Rel(zernio, social, "Publishes to", "HTTPS")
    Rel(ogen, firecrawl, "Scrapes URLs", "HTTPS")
    Rel(ogen, resend, "Sends email", "HTTPS")
    Rel(ogen, sentry, "Errors & traces", "HTTPS / OTLP")

    UpdateElementStyle(creator, $bgColor="#08427b", $fontColor="#ffffff", $borderColor="#052e56")
    UpdateElementStyle(admin, $bgColor="#08427b", $fontColor="#ffffff", $borderColor="#052e56")
    UpdateElementStyle(ogen, $bgColor="#1168bd", $fontColor="#ffffff", $borderColor="#0b4884")
    UpdateElementStyle(anthropic, $bgColor="#999999", $fontColor="#ffffff", $borderColor="#6b6b6b")
    UpdateElementStyle(gemini, $bgColor="#999999", $fontColor="#ffffff", $borderColor="#6b6b6b")
    UpdateElementStyle(zernio, $bgColor="#999999", $fontColor="#ffffff", $borderColor="#6b6b6b")
    UpdateElementStyle(social, $bgColor="#999999", $fontColor="#ffffff", $borderColor="#6b6b6b")
    UpdateElementStyle(firecrawl, $bgColor="#999999", $fontColor="#ffffff", $borderColor="#6b6b6b")
    UpdateElementStyle(resend, $bgColor="#999999", $fontColor="#ffffff", $borderColor="#6b6b6b")
    UpdateElementStyle(sentry, $bgColor="#999999", $fontColor="#ffffff", $borderColor="#6b6b6b")
    UpdateRelStyle(creator, ogen, $textColor="#444444", $lineColor="#707070")
    UpdateRelStyle(admin, ogen, $textColor="#444444", $lineColor="#707070")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Containers (C4 level 2)

Inside the Ogen boundary, the API monolith is the hub: it serves the SPA over REST + SSE, owns the control-plane and analytics databases, hands its background jobs to river-service (and serves their steps), runs the Genkit AI flows, and exposes an internal-only gRPC surface that Harbor uses to manage secrets, tenants, plans, the platform catalog, per-flow model assignments, email, and announcements. PDF, video, document, audio, and image processing are split out into private-network sidecar services.

This is the beginning of the README. Read the rest at the original. Read the full README ↗