Skip to content

Architecture ​

cicada is a Rust workspace built on ports-and-adapters (DDD). The point of the split: the same reconciliation engine powers the cicada CLI a human runs and the MCP tools an agent drives — with zero business-logic duplication.

Layers ​

Interfaces (CLI / MCP)        thin adapters, no business logic
        │
Application (use cases)       Validate · Plan · Apply · Refresh ·
        │                     Drift · QueryRange · Show · Fmt
        │
Domain (entities + services)  Calendar · Event · Recurrence ·
        │                     Attendee · Reminder · Time ·
        │                     EventDiffer · RecurrenceExpander ·
        │                     CapabilityChecker
        │
Ports (traits)                CalendarProvider · StateStore ·
                              AuthProvider · Clock · Logger ·
                              SecretStore · Http

cicada-core holds domain, application, and ports — and is pure: no std::fs, no tokio, no HTTP types, no provider SDKs. Purity is what makes "reuse across CLI and MCP" real rather than aspirational: every side effect crosses a port trait, so the whole domain is testable with in-memory fakes — fast, deterministic, no network.

The seven ports ​

PortResponsibilityShipped adapterPossible adapters
CalendarProviderlist/get/create/update/delete events, findByTag, freeBusy, capabilitiescicada-google (+ FakeFileProvider for tests)Teams, CalDAV
StateStorerecorded state + apply journalcicada-state (versioned YAML on disk, locked, atomic)GCS, S3 backends
AuthProvidercredential acquisitionGoogle OAuth / service-account / static tokenper-provider auth
Clockinjectable now()system clockfake clock (tests, golden plans)
Loggerstructured loggingconsoletracing subscribers
SecretStoretoken persistencefile store, 0600OS keychain
Httpinjectable fetchreqwest + retry wrapperrecorded-fixture client

ProviderCapabilities is first-class on CalendarProvider: attendee limits, reminder kinds, recurrence edge cases, conferencing kinds, notification suppression, tagging, conditional writes. The planner consults capabilities at plan time and rejects or warns on unsupported desired states — this is what makes multi-provider work honestly instead of silently dropping fields.

Why a pure core ​

  • Two interfaces, one engine. cicada (the tamias bins[] shim over tamias-driver-cicada cli) and the driver's mcp surface are thin shells that dispatch the same cicada-core use cases. Agents get the identical lifecycle humans get — every bounded verb is a cli.<verb> op, and apply --plan-digest carries the preview→apply gate engine-side.
  • Testability. Domain and planning logic run against in-memory fakes; the Google adapter is exercised by recorded HTTP fixtures. The full lifecycle shipped and passed end-to-end tests before any Google code existed.
  • Extensibility. New providers, state backends, auth methods, and interfaces are new adapters. The core never changes.

Crates ​

cratelayerpurpose
cicada-coredomaincicada-core — pure domain, ports, and planning scaffolding. Layered per ADR-0001: domain holds entities and value objects, application the use cases, ports the seven traits implemented by adap…
cicada-googleadaptercicada-google — the Google Calendar provider adapter (ADR-0001 §10 step 6).
cicada-schemaadaptercicada-schema — the YAML DSL: Kubernetes-style envelope (apiVersion: cicada/v1, kind:) parsed into cicada-core domain types. Two documents (ADR-0001 §6, ADR-0002 §9):
cicada-shelladaptercicada-shell — the plumbing every user-facing interface shares. cicada-core is pure; adapters live in their own crates.
cicada-stateadapterJsonFileStateStore — the file-backed StateStore adapter (ADR-0002 §7). The state file is YAML in the cicada/state-v1 shape:
cicadaenginecicada — calendars as code: the engine lib + cicada CLI (init/validate/list/plan/apply/refresh/drift/range/show/fmt/provider)
cicada-driverdrivertamias-driver-cicada — pavo engine-ops driver over the cicada CLI plus tamias content driver for type: cicada packages
cicada-testkittestkitcicada-testkit — reusable fakes and conformance helpers for tests across the workspace.
xtasktoolingxtask — workspace automation: check / test / coverage / pack / install / fmt.

Single write path ​

All mutations flow through plan/apply on declared YAML — the CLI has no cicada event create and MCP has no events.create. Two write paths would create unmanaged events that immediately surface as drift; one lifecycle keeps the world consistent.

Time model ​

Recurring events are stored as (local wall time, IANA zone) and materialised to instants at expansion — DST shifts keep a 09:00 standup at 09:00 local. Bare-UTC storage of recurring times is the classic calendar bug and is banned in core.

See Boundaries for owns / doesn't-own.

Where it sits ​

In the org's layering — delivery (tamias distribution, scarab config/templates, tarsi releases, bupha CI, hypha entity sync) → memory (myco records, kuda code maps) → process (sturn coordination, cuora secrets, mimus proofs, cicada schedules, lasius workspace, sepia sessions, peregrin campaigns) → interface (pavo views, MCP fronts).

Cicada is a process-layer organism — infrastructure-style reconciliation for calendars. Humans drive cicada verbs; agents drive the same verbs as cli.* ops or MCP tools; both land on the identical cicada-core use cases, with the planDigest gate making preview→apply explicit on every surface.