# cap-go/capgo architecture

> Architecture diagram of the GitHub repository cap-go/capgo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cap-go/capgo
- Repository: https://github.com/cap-go/capgo

## Overview

##### Project Type & Purpose
- Project Type: Full‑stack, multi‑platform app (web SPA, iOS, Android) plus supporting serverless back‑ends.
- Purpose: “Capgo” provides instant over-the-air updates for Capacitor-based mobile apps.  It has:
- A Vue3/Vite single‑page web app (also wrapped via Capacitor for mobile)
- Serverless APIs on Cloudflare Workers handling ~99% of traffic
- Supabase (Postgres + Functions + Triggers) for internal cron jobs, data storage, authentication, business logic
- Scripts to manage Stripe billing, S3 assets, migrations

##### File Structure & Key Components
- Frontend (src/, public/, index.html, Vite config)
- Mobile wrappers (android/, ios/) via Capacitor
- Cloudflare Workers (cloudflare_workers/)
- Supabase backend:
- Functions (supabase/functions/_backend & public)
- Database migrations & triggers (supabase/migrations, tests)
- Deployment workflows (GitHub Actions, Netlify, Fastlane, Codemagic)
- Utility scripts (scripts/) for data sync, billing, deployments

##### Main Components
a. Client Apps
- Web SPA (Vue3 + Vite + FormKit + Pinia)
- Mobile (Capacitor bridge → iOS / Android native shells)
b. Edge/API Layer
- Cloudflare Workers (REST endpoints for update manifest, file delivery, channels, stats)
c. Core Business Backend
- Supabase Functions & Triggers (CRUD APIs, cron jobs, RLS, business logic, replication)
- Postgres DB (with migrations, RLS policies)
d. External Services
- Stripe (billing, portal)
- AWS S3 / R2 (artifact storage)
- PostHog / Plausible (analytics)
- LogSnag / Discord (notifications)
e. CI/CD & Dev Tools
- GitHub Actions (build, test, bump, deploy)
- Netlify / Cloudflare Pages (web hosting)
- Fastlane / Codemagic (mobile app store deploy)

##### Relationships & Data Flows
- Clients → Cloudflare Workers (HTTPS requests for manifests, bundle downloads)
- Cloudflare Workers ↔ Supabase Functions (invoke internal APIs for auth, stats, channels)
- Supabase Functions ↔ Postgres DB (read/write via RLS)
- Triggers → Functions (on‑insert/update events drive cron & background processing)
- Billing workflows: Stripe webhooks → Supabase triggers → DB updates
- CI/CD pipelines → deploy front‑end & functions to CF, Netlify, Supabase

##### Architectural Patterns & Principles
- SPA + PWA on web; wrapped in Capacitor for native mobile
- Serverless microservices (CF Workers for edge/low‑latency API)
- Event‑driven backend (DB triggers + scheduled cron)
- Strict RLS and API surface broken into “public” vs “private” functions
- Infrastructure as Code (wrangler.json, supabase config, GitHub workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        SPA["Web SPA"]:::client
        SRC["src/"]:::client
        PUBLIC["public/"]:::client
        INDEX["index.html"]:::client
        VITE["vite.config.mts"]:::client
        FK_CFG["formkit.config.ts"]:::client
        FK_THEME["formkit.theme.ts"]:::client
        SPA --> SRC
        SPA --> PUBLIC
        SPA --> INDEX
        SPA --> VITE
        SPA --> FK_CFG
        SPA --> FK_THEME
        Mobile["Mobile Apps"]:::client
        ANDR["android/"]:::client
        IOS["ios/"]:::client
        Mobile --> ANDR
        Mobile --> IOS
    end

    %% Edge/API Layer
    subgraph "Edge Layer"
        direction TB
        CF_API["CF Worker: api/index.ts"]:::edge
        CF_FILES["CF Worker: files/index.ts"]:::edge
        CF_PLUGIN["CF Worker: plugin/index.ts"]:::edge
        CF_WRAP1["wrangler.json (api)"]:::edge
        CF_WRAP2["wrangler.json (files)"]:::edge
        CF_WRAP3["wrangler.json (plugin)"]:::edge
        CF_API --> CF_WRAP1
        CF_FILES --> CF_WRAP2
        CF_PLUGIN --> CF_WRAP3

        Netlify_UPD["Netlify Edge: updates.ts"]:::edge
        Netlify_CHN["Netlify Edge: channel.ts"]:::edge
        Netlify_DEV["Netlify Edge: device.ts"]:::edge
        Netlify_STS["Netlify Edge: stats.ts"]:::edge
        Netlify_OTH["Netlify Edge: other .ts"]:::edge
    end

    %% Supabase Backend
    subgraph "Supabase Backend"
        direction TB
        subgraph "Public Functions"
            direction TB
            PUB_APIKEY["apikey/index.ts"]:::backend
            PUB_APP["app/*.ts"]:::backend
            PUB_BNDL["bundle/*.ts"]:::backend
            PUB_CHNL["channel/*.ts"]:::backend
            PUB_DEV["device/*.ts"]:::backend
            PUB_ORG["organization/**/*.ts"]:::backend
            PUB_STATS["statistics/index.ts"]:::backend
            PUB_OK["ok.ts"]:::backend
        end
        subgraph "Private Functions"
            direction TB
            PRIV_DEV["create_device.ts"]:::backend
            PRIV_STRP["stripe_checkout.ts"]:::backend
            PRIV_PORT["stripe_portal.ts"]:::backend
            PRIV_OTH["other .ts"]:::backend
        end
        subgraph "Triggers & Cron"
            direction TB
            TR_VER["on_version_create.ts"]:::backend
            TR_CRON["cron_stats.ts"]:::backend
            TR_STRP["stripe_event.ts"]:::backend
            TR_OTH["other .ts"]:::backend
        end
        PUB_APIKEY --> PUB_OK
    end

    %% Database & Migrations
    subgraph "Database"
        direction TB
        DB["Postgres DB"]:::backend
        MIG["migrations/*.sql"]:::backend
        CFG["config.toml"]:::backend
        DB --> MIG
        DB --> CFG
    end

    %% Utility Scripts
    subgraph "Scripts" 
        direction TB
        S1["add_replicate.ts"]:::script
        S2["sync_stripe_status.ts"]:::script
        S3["check_r2.ts"]:::script
        S4["deploy_cf_backend_env.mjs"]:::script
        S_OTH["other scripts"]:::script
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Stripe["Stripe"]:::external
        S3["AWS S3 / R2"]:::external
        Analytics["PostHog / Plausible"]:::external
        Notify["LogSnag / Discord"]:::external
    end

    %% CI/CD & Dev Tools
    subgraph "CI/CD & Dev Tools"
        direction TB
        GH_BUILD[".github/workflows/build_and_deploy.yml"]:::ci
        GH_IOS["build_mobile_ios.yml"]:::ci
        GH_ANDR["build_mobile_android.yml"]:::ci
        GH_TEST["tests.yml"]:::ci
        NETLIFY_CFG["netlify.toml"]:::ci
        CODEMAGIC["codemagic.yaml"]:::ci
        FASTLANE_DIR["fastlane/"]:::ci
        FASTFILE["Fastfile"]:::ci
    end

    %% Connections
    SPA -->|HTTP| CF_API
    Mobile -->|HTTP| CF_API
    CF_API -->|Invoke| PUB_APIKEY
    CF_FILES -->|Serve| S3
    Netlify_UPD -->|HTTP| PUB_BNDL
    PUB_APIKEY -->|CRUD| DB
    PRIV_STRP -->|Webhook| Stripe
    TR_STRP -->|DB Event| PRIV_STRP
    MIG -->|Schema| DB
    S1 -->|Sync| DB
    GH_BUILD -->|Deploy SPA| SPA
    GH_BUILD -->|Deploy CF| CF_API
    GH_BUILD -->|Deploy Supabase| PUB_APIKEY
    CODEMAGIC -->|Deploy Mobile| Mobile

    %% Click Events
    click SRC "https://github.com/cap-go/capgo/tree/main/src/"
    click PUBLIC "https://github.com/cap-go/capgo/tree/main/public/"
    click INDEX "https://github.com/cap-go/capgo/blob/main/index.html"
    click VITE "https://github.com/cap-go/capgo/blob/main/vite.config.mts"
    click FK_CFG "https://github.com/cap-go/capgo/blob/main/formkit.config.ts"
    click FK_THEME "https://github.com/cap-go/capgo/blob/main/formkit.theme.ts"
    click ANDR "https://github.com/cap-go/capgo/tree/main/android/"
    click IOS "https://github.com/cap-go/capgo/tree/main/ios/"
    click CF_API "https://github.com/cap-go/capgo/blob/main/cloudflare_workers/api/index.ts"
    click CF_FILES "https://github.com/cap-go/capgo/blob/main/cloudflare_workers/files/index.ts"
    click CF_PLUGIN "https://github.com/cap-go/capgo/blob/main/cloudflare_workers/plugin/index.ts"
    click CF_WRAP1 "https://github.com/cap-go/capgo/blob/main/cloudflare_workers/api/wrangler.json"
    click CF_WRAP2 "https://github.com/cap-go/capgo/blob/main/cloudflare_workers/files/wrangler.json"
    click CF_WRAP3 "https://github.com/cap-go/capgo/blob/main/cloudflare_workers/plugin/wrangler.json"
    click Netlify_UPD "https://github.com/cap-go/capgo/blob/main/netlify/edge-functions/updates.ts"
    click Netlify_CHN "https://github.com/cap-go/capgo/blob/main/netlify/edge-functions/channel.ts"
    click Netlify_DEV "https://github.com/cap-go/capgo/blob/main/netlify/edge-functions/device.ts"
    click Netlify_STS "https://github.com/cap-go/capgo/blob/main/netlify/edge-functions/stats.ts"
    click PUB_APIKEY "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/public/apikey/index.ts"
    click PUB_APP "https://github.com/cap-go/capgo/tree/main/supabase/functions/_backend/public/app/"
    click PUB_BNDL "https://github.com/cap-go/capgo/tree/main/supabase/functions/_backend/public/bundle/"
    click PUB_CHNL "https://github.com/cap-go/capgo/tree/main/supabase/functions/_backend/public/channel/"
    click PUB_DEV "https://github.com/cap-go/capgo/tree/main/supabase/functions/_backend/public/device/"
    click PUB_ORG "https://github.com/cap-go/capgo/tree/main/supabase/functions/_backend/public/organization/"
    click PUB_STATS "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/public/statistics/index.ts"
    click PUB_OK "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/public/ok.ts"
    click PRIV_DEV "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/private/create_device.ts"
    click PRIV_STRP "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/private/stripe_checkout.ts"
    click PRIV_PORT "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/private/stripe_portal.ts"
    click TR_VER "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/triggers/on_version_create.ts"
    click TR_CRON "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/triggers/cron_stats.ts"
    click TR_STRP "https://github.com/cap-go/capgo/blob/main/supabase/functions/_backend/triggers/stripe_event.ts"
    click MIG "https://github.com/cap-go/capgo/tree/main/supabase/migrations/"
    click CFG "https://github.com/cap-go/capgo/blob/main/supabase/config.toml"
    click S1 "https://github.com/cap-go/capgo/blob/main/scripts/add_replicate.ts"
    click S2 "https://github.com/cap-go/capgo/blob/main/scripts/sync_stripe_status.ts"
    click S3 "https://github.com/cap-go/capgo/blob/main/scripts/check_r2.ts"
    click S4 "https://github.com/cap-go/capgo/blob/main/scripts/deploy_cf_backend_env.mjs"
    click GH_BUILD "https://github.com/cap-go/capgo/blob/main/.github/workflows/build_and_deploy.yml"
    click GH_IOS "https://github.com/cap-go/capgo/blob/main/.github/workflows/build_mobile_ios.yml"
    click GH_ANDR "https://github.com/cap-go/capgo/blob/main/.github/workflows/build_mobile_android.yml"
    click GH_TEST "https://github.com/cap-go/capgo/blob/main/.github/workflows/tests.yml"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#009AFF,color:#000
    classDef edge fill:#D1F7C4,stroke:#2D9730,color:#000
    classDef backend fill:#FFE4B3,stroke:#E27A00,color:#000
    classDef external fill:#F0F0F0,stroke:#888,color:#000
    classDef script fill:#EAD1DC,stroke:#B03A57,color:#000
    classDef ci fill:#E0E0E0,stroke:#555,color:#000
```
