# abdulmumin1/owostack architecture

> Architecture diagram of the GitHub repository abdulmumin1/owostack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdulmumin1/owostack
- Repository: https://github.com/abdulmumin1/owostack

## Overview

Owostack is a billing engine for AI SaaS: applications define a catalog, then use its runtime to attach plans, check feature access, and record usage. The API handles billing and usage, with provider adapters for payment gateways and analytics/event handling alongside it. The dashboard manages organizations and billing configuration; the CLI syncs catalog configuration. The README documents Durable Objects and Workflows as infrastructure, but sampled excerpts do not establish their detailed call paths.

Main entry points: [`apps/api/src/routes/api`](https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/routes/api) (Runtime API routes), [`packages/core/src/index.ts`](https://github.com/abdulmumin1/owostack/blob/main/packages/core/src/index.ts) (TypeScript SDK), [`apps/api/src/index.ts`](https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/index.ts) (Workers API), [`apps/api/src/routes/dashboard`](https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/routes/dashboard) (Dashboard routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SDK and catalog"]
  node_sdk["TypeScript SDK<br/>[index.ts]"]
  node_catalog["Catalog definitions<br/>[catalog.ts]"]
end

subgraph group_api["Billing API"]
  node_api["Workers API<br/>[index.ts]"]
  node_publicroutes["Runtime API routes"]
  node_dashboardroutes["Dashboard routes"]
  node_usage["Usage metering<br/>[usage-meter.ts]"]
  node_entitlements["Entitlements and plans<br/>[entitlements.ts]"]
  node_billing["Billing workflows"]
  node_webhooks["Webhook processing<br/>[index.ts]"]
  node_providerlogic["Provider integration logic<br/>[providers.ts]"]
end

subgraph group_state["State and analytics"]
  node_ledger[("Usage ledger<br/>[usage-ledger.ts]")]
  node_schema[("Billing database schema")]
  node_analytics["Analytics events<br/>[index.ts]"]
end

subgraph group_integrations["Provider integrations"]
  node_adapters["Payment adapters<br/>[index.ts]"]
end

subgraph group_interfaces["Product interfaces"]
  node_cli["Catalog CLI<br/>[index.ts]"]
  node_dashboard["Admin dashboard<br/>[auth-client.ts]"]
  node_demo["Billing demo app<br/>[owo.ts]"]
end

node_developer(("Application developer"))
node_application(("Customer application"))
node_gateway["Payment gateways"]
node_pipeline["Analytics pipeline"]
node_cloudflare["Cloudflare runtime"]

node_developer -->|"defines catalog"| node_catalog
node_catalog -->|"configures"| node_sdk
node_application -->|"calls runtime"| node_sdk
node_sdk -->|"requests billing"| node_publicroutes
node_cli -->|"loads config"| node_catalog
node_cli -->|"syncs catalog"| node_publicroutes
node_dashboard -->|"manages billing"| node_dashboardroutes
node_demo -->|"calls runtime"| node_sdk
node_publicroutes -->|"checks access"| node_entitlements
node_publicroutes -->|"tracks usage"| node_usage
node_publicroutes -->|"handles billing"| node_billing
node_publicroutes -->|"uses providers"| node_providerlogic
node_dashboardroutes -->|"manages plans"| node_entitlements
node_dashboardroutes -->|"reads usage"| node_usage
node_api -->|"dispatches events"| node_webhooks
node_webhooks -->|"updates billing"| node_billing
node_providerlogic -->|"selects adapter"| node_adapters
node_adapters -->|"calls gateway"| node_gateway
node_usage -->|"records usage"| node_ledger
node_billing -->|"persists billing"| node_schema
node_entitlements -->|"reads configuration"| node_schema
node_api -.->|"records events"| node_analytics
node_analytics -.->|"sends events"| node_pipeline
node_api -->|"runs on"| node_cloudflare

click node_sdk "https://github.com/abdulmumin1/owostack/blob/main/packages/core/src/index.ts"
click node_catalog "https://github.com/abdulmumin1/owostack/blob/main/packages/core/src/catalog.ts"
click node_cli "https://github.com/abdulmumin1/owostack/blob/main/packages/cli/src/index.ts"
click node_dashboard "https://github.com/abdulmumin1/owostack/blob/main/apps/dashboard/src/lib/auth-client.ts"
click node_demo "https://github.com/abdulmumin1/owostack/blob/main/apps/demo-app/src/lib/server/owo.ts"
click node_api "https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/index.ts"
click node_publicroutes "https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/routes/api"
click node_dashboardroutes "https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/routes/dashboard"
click node_usage "https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/usage-meter.ts"
click node_entitlements "https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/entitlements.ts"
click node_billing "https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/lib/workflows"
click node_webhooks "https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/webhooks/index.ts"
click node_providerlogic "https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/providers.ts"
click node_ledger "https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/usage-ledger.ts"
click node_schema "https://github.com/abdulmumin1/owostack/tree/main/packages/db/src/schema"
click node_analytics "https://github.com/abdulmumin1/owostack/blob/main/packages/analytics/src/index.ts"
click node_adapters "https://github.com/abdulmumin1/owostack/blob/main/packages/adapters/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_catalog toneBlue
class node_api,node_publicroutes,node_dashboardroutes,node_usage,node_entitlements,node_billing,node_webhooks,node_providerlogic toneAmber
class node_ledger,node_schema,node_analytics toneMint
class node_adapters toneRose
class node_cli,node_dashboard,node_demo,node_developer,node_application,node_gateway,node_pipeline,node_cloudflare toneIndigo
```

## Components

### SDK and catalog

- [TypeScript SDK](https://github.com/abdulmumin1/owostack/blob/main/packages/core/src/index.ts): `packages/core/src/index.ts`
- [Catalog definitions](https://github.com/abdulmumin1/owostack/blob/main/packages/core/src/catalog.ts): `packages/core/src/catalog.ts`

### Billing API

- [Workers API](https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Runtime API routes](https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/routes/api): `apps/api/src/routes/api`
- [Dashboard routes](https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/routes/dashboard): `apps/api/src/routes/dashboard`
- [Usage metering](https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/usage-meter.ts): `apps/api/src/lib/usage-meter.ts`
- [Entitlements and plans](https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/entitlements.ts): `apps/api/src/lib/entitlements.ts`
- [Billing workflows](https://github.com/abdulmumin1/owostack/tree/main/apps/api/src/lib/workflows): `apps/api/src/lib/workflows`
- [Webhook processing](https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/webhooks/index.ts): `apps/api/src/lib/webhooks/index.ts`
- [Provider integration logic](https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/providers.ts): `apps/api/src/lib/providers.ts`

### State and analytics

- [Usage ledger](https://github.com/abdulmumin1/owostack/blob/main/apps/api/src/lib/usage-ledger.ts): `apps/api/src/lib/usage-ledger.ts`
- [Billing database schema](https://github.com/abdulmumin1/owostack/tree/main/packages/db/src/schema): `packages/db/src/schema`
- [Analytics events](https://github.com/abdulmumin1/owostack/blob/main/packages/analytics/src/index.ts): `packages/analytics/src/index.ts`

### Provider integrations

- [Payment adapters](https://github.com/abdulmumin1/owostack/blob/main/packages/adapters/src/index.ts): `packages/adapters/src/index.ts`

### Product interfaces

- [Catalog CLI](https://github.com/abdulmumin1/owostack/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`
- [Admin dashboard](https://github.com/abdulmumin1/owostack/blob/main/apps/dashboard/src/lib/auth-client.ts): `apps/dashboard/src/lib/auth-client.ts`
- [Billing demo app](https://github.com/abdulmumin1/owostack/blob/main/apps/demo-app/src/lib/server/owo.ts): `apps/demo-app/src/lib/server/owo.ts`

### Other components

- **Application developer**
- **Customer application**
- **Payment gateways**
- **Analytics pipeline**
- **Cloudflare runtime**

## Connections

- Application developer → Catalog definitions: defines catalog
- Catalog definitions → TypeScript SDK: configures
- Customer application → TypeScript SDK: calls runtime
- TypeScript SDK → Runtime API routes: requests billing
- Catalog CLI → Catalog definitions: loads config
- Catalog CLI → Runtime API routes: syncs catalog
- Admin dashboard → Dashboard routes: manages billing
- Billing demo app → TypeScript SDK: calls runtime
- Runtime API routes → Entitlements and plans: checks access
- Runtime API routes → Usage metering: tracks usage
- Runtime API routes → Billing workflows: handles billing
- Runtime API routes → Provider integration logic: uses providers
- Dashboard routes → Entitlements and plans: manages plans
- Dashboard routes → Usage metering: reads usage
- Workers API → Webhook processing: dispatches events
- Webhook processing → Billing workflows: updates billing
- Provider integration logic → Payment adapters: selects adapter
- Payment adapters → Payment gateways: calls gateway
- Usage metering → Usage ledger: records usage
- Billing workflows → Billing database schema: persists billing
- Entitlements and plans → Billing database schema: reads configuration
- Workers API → Analytics events: records events
- Analytics events → Analytics pipeline: sends events
- Workers API → Cloudflare runtime: runs on