Architecture at a Glance

flowchart LR
  subgraph Clients
    CLI
    Desktop
    iOS
  end

  subgraph Otso["Otso core"]
    SDK["SDK & runtime"]
    API["HTTP API"]
    DB[("Event store")]
    PR["Projections"]
    Plugins["Plugins"]
    SDK --> DB
    DB --> PR
    SDK --> API
    Plugins --> SDK
  end

  CLI --> SDK
  Desktop --> SDK
  iOS --> SDK

  Sources["Sources"] -- import --> Plugins
  SDK -- publish --> Publishers["Publishers / networks"]
  PR --> Site["Your site & dashboards"]
  API --> Emulators["Emulators"]

  classDef store fill:#2b5,stroke:#185,stroke-width:1,color:#fff;
  class DB,PR store;

Core concepts

• Events: append‑only records of actions (imported, enriched, published). Easy to audit and replay.
• Projections: derived tables/JSON/search indexes for fast reads. Rebuildable on demand.
• Adapters: thin plugins for sources (imports) and publishers (POSSE, Micropub).

Storage: SQLite or Postgres

• Start with SQLite: fast, simple, great for local use and CLIs.
• Move to Postgres when you want concurrent writers, external services, or hosted ops.
• Replication and backup: use Litestream/LiteFS for SQLite; standard tools for Postgres.

Import flow (any API or archive)

sequenceDiagram
  autonumber
  participant Src as Source API/Archive
  participant CLI as Otso CLI
  participant DB as Store (SQLite/Postgres)
  participant PR as Projections

  Src->>CLI: Fetch page (cursor / ETag / since‑ID)
  CLI->>CLI: Normalize → kinds + media
  CLI->>DB: Upsert with idempotency key
  DB-->>CLI: Insert/Update (or No‑op)
  CLI->>PR: Emit events → update projections

Publish flow (your site is the source)

sequenceDiagram
  autonumber
  participant You as You
  participant CLI as Otso CLI
  participant Site as Your Site (Micropub)
  participant Net as Networks (POSSE)
  participant WM as Webmention

  You->>CLI: Compose post
  CLI->>Site: Micropub create
  Site-->>CLI: 201 Created + canonical URL
  CLI->>Net: Cross‑post with canonical link
  Site->>WM: Send/Receive webmentions

Privacy & visibility

flowchart LR
  Item[Content item] -->|public| Pub[Public projections & feeds]
  Item -->|unlisted| Unl[Permalink only
no index/feed]
  Item -->|private| Priv[Private tools only]
  Item -->|secret| Sec[Secure projection
or encrypted vault]
  Idx[[Search Index]] -. excludes .-> Priv
  Idx -. excludes .-> Sec

• Credentials live in env vars or OS keychain; never in the repo or search indexes.

What lives where

• Core SDK: stable data model, command surface, and utilities (rate limits, media).
• Plugins: per‑service logic (API/format quirks) and small mapping functions.
• Site/UI: thin layers over projections; easy to swap or customize.

This separation keeps Otso fast to use, easy to reason about, and safe to extend.