Skip to content

PRINCIPLES.md

Latest commit

 

History

History
40 lines (27 loc) · 3.49 KB

PRINCIPLES.md

File metadata and controls

40 lines (27 loc) · 3.49 KB

Architecture Principles

  1. Contract-first, MVP-faithful

    • All specs in this repo describe behavior that exists in a running system. Contracts are extracted from code, not imagined ahead of it. Forward-looking ideas are called out as non-normative.

  2. Two-plane separation: control vs. delivery

    • REST is the transactional control-plane (create session, inspect session, start checkout, receive webhook). Stream is the data-plane (deliver analysis output and visibility decisions). Analysis content never flows over REST.

  3. Execution ≠ Visibility

    • The system distinguishes between “what the model executed” and “what the user can see”. Paywalls and entitlement only gate visibility; they do not imply cancellation of underlying execution.

  4. Session-scoped, account-free surface

    • C1 is intentionally anonymous: contracts are expressed in terms of (sessionId, topic, resultKey) instead of user accounts. This keeps the integration surface small and makes it easy to embed into many products.

  5. Minimal, explicit correlation model

    • Clients correlate by (sessionId, topic); the backend additionally uses an opaque resultKey for replay and caching. There is no cursor or resumable offset; correlation relies on (sessionId, topic, resultKey).

  6. Append-only streaming with explicit termination

    • Streams are modeled as ordered sequences of JSON messages. A small, explicit set of events (analysisStatus(completed), paywall, response, unlock(content), error) marks termination. Transport disconnect is treated as terminal failure of the stream instance (see stream_protocol.md).

  7. Visibility is stateful, transport is disposable

    • Transport disconnect is treated as failure of the current stream instance, not loss of business state. Clients can reconnect and re-derive visibility from REST and new stream requests; protocols do not attempt fine-grained resume.

  8. Entitlement is per (sessionId, topic)

    • Billing and entitlement are defined as “Is this (sessionId, topic) entitled to full visibility?”. This matches the UX funnel (single session, multiple topics) and keeps billing state aligned with what the user sees.

  9. Payment provider–agnostic integration

    • The contracts describe “checkout sessions” and “payment provider webhooks” instead of binding to a specific vendor. Vendor choice is an implementation detail behind the same webhook + checkout surface.

  10. Domain- and model-agnostic contracts

    • C1 does not encode domain semantics, business positioning, or model/vendor details. These are layered above the contracts so that the same primitives can be reused across multiple products and model stacks.

  11. Small, composable primitives

    • The surface area is intentionally small: a handful of REST endpoints and six stream event types. Higher-level UX flows (client state machine) are built by composing these primitives rather than extending the protocol.

  12. Clear layering between normative and informative docs

    • rest_api_contract.md and stream_protocol.md are normative. C1_client_server_contract.md, client_state_machine.md, and higher-level docs are informative, explaining one concrete realization without constraining other clients.

  13. Evolvable but conservative

    • Changes prefer compatibility with existing clients: new capabilities should be additive, keep existing termination rules intact, and avoid redefining the meaning of existing fields or events.