# iamsuudi/swoff architecture

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

- Interactive diagram: https://gitdiagram.com/iamsuudi/swoff
- Repository: https://github.com/iamsuudi/swoff

## Overview

Swoff is a monorepo for offline-first web tooling. Its principal workflow is configuring and invoking the CLI to generate a service worker and client runtime that an application serves and uses. The README also documents a separate PWA asset generator, but its implementation is not present in the supplied tree; its capabilities are shown without inferring internal wiring. The sampled sources show a storage helper generator and framework hooks, while most feature wiring is documented rather than sampled.

Main entry points: [`apps/cli/src/lib/commands/generate.ts`](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/commands/generate.ts) (CLI commands), [`apps/cli/src/lib/generators/sw-sections/fetch-handler.ts`](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/sw-sections/fetch-handler.ts) (Fetch strategies), [`apps/cli/src/runtime/mutation-queue.ts`](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/mutation-queue.ts) (Mutation queue), [`apps/cli/src/runtime/client-injector.ts`](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/client-injector.ts) (Client runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli_entry["CLI entry<br/>[index.ts]"]
  node_commands["CLI commands<br/>[generate.ts]"]
  node_config["Config loading<br/>[loader.ts]"]
  node_validation["Config validation<br/>[validator.ts]"]
  node_framework_detect["Stack detection"]
end

subgraph group_generation["Code generation"]
  node_swgen["Service worker generator<br/>[sw-generator.ts]"]
  node_filegens["Runtime file generators"]
  node_adapters["Framework adapters"]
end

subgraph group_offline["Offline runtime"]
  node_client_runtime["Client runtime<br/>[client-injector.ts]"]
  node_sw_fetch["Fetch strategies<br/>[fetch-handler.ts]"]
  node_tag_invalidation["Tag invalidation<br/>[tag-management.ts]"]
  node_mutation_queue["Mutation queue<br/>[mutation-queue.ts]"]
end

subgraph group_integrations["App integrations"]
  node_framework_hooks["Framework hooks<br/>[useSwoffFetch.tsx]"]
  node_storage["Storage utilities<br/>[storage.ts]"]
  node_asset_tool["PWA asset generator"]
end

node_developer(("App developer"))
node_configfile["Swoff config"]
node_generated["Generated project files"]
node_application["Web application"]
node_browser_cache[("Browser Cache API")]
node_indexeddb[("IndexedDB")]
node_network(("Application server"))
node_push_server(("Push or SSE server"))
node_asset_outputs["PWA assets"]

node_developer -->|"runs"| node_cli_entry
node_developer -->|"configures"| node_configfile
node_cli_entry -->|"dispatches"| node_commands
node_commands -->|"loads"| node_config
node_commands -->|"validates"| node_validation
node_configfile -->|"read by"| node_config
node_commands -->|"detects stack"| node_framework_detect
node_commands -->|"generates worker"| node_swgen
node_commands -->|"generates runtime"| node_filegens
node_commands -->|"generates adapters"| node_adapters
node_swgen -->|"writes worker"| node_generated
node_filegens -->|"writes runtime"| node_generated
node_adapters -->|"writes hooks"| node_generated
node_developer -->|"integrates files"| node_application
node_application -->|"initializes"| node_client_runtime
node_client_runtime -->|"registers worker"| node_sw_fetch
node_sw_fetch -->|"reads and writes"| node_browser_cache
node_sw_fetch -->|"fetches requests"| node_network
node_sw_fetch -->|"tracks tags"| node_tag_invalidation
node_sw_fetch -->|"queues mutations"| node_mutation_queue
node_mutation_queue -->|"persists queue"| node_indexeddb
node_mutation_queue -->|"retries mutations"| node_network
node_application -.->|"uses hooks"| node_framework_hooks
node_framework_hooks -.->|"calls runtime"| node_client_runtime
node_application -.->|"checks quota"| node_storage
node_push_server -.->|"push events"| node_sw_fetch
node_developer -.->|"runs separately"| node_asset_tool
node_asset_tool -.->|"generates assets"| node_asset_outputs

click node_cli_entry "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/index.ts"
click node_commands "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/commands/generate.ts"
click node_config "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/config/loader.ts"
click node_validation "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/config/validator.ts"
click node_framework_detect "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/utils/detect-framework.ts"
click node_swgen "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/sw-generator.ts"
click node_filegens "https://github.com/iamsuudi/swoff/tree/main/apps/cli/src/lib/generators/file-generators"
click node_adapters "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/file-generators/generate-framework-adapters.ts"
click node_client_runtime "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/client-injector.ts"
click node_sw_fetch "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/sw-sections/fetch-handler.ts"
click node_tag_invalidation "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/sw-sections/tag-management.ts"
click node_mutation_queue "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/mutation-queue.ts"
click node_framework_hooks "https://github.com/iamsuudi/swoff/blob/main/apps/cli/templates/react/useSwoffFetch.tsx"
click node_storage "https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/storage.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_cli_entry,node_commands,node_config,node_validation,node_framework_detect toneBlue
class node_swgen,node_filegens,node_adapters,node_browser_cache,node_indexeddb toneAmber
class node_client_runtime,node_sw_fetch,node_tag_invalidation,node_mutation_queue,node_network,node_push_server toneMint
class node_framework_hooks,node_storage,node_asset_tool toneRose
class node_developer,node_configfile,node_generated,node_application,node_asset_outputs toneIndigo
```

## Components

### CLI workflow

- [CLI entry](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/index.ts): `apps/cli/src/index.ts`
- [CLI commands](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/commands/generate.ts): `apps/cli/src/lib/commands/generate.ts`
- [Config loading](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/config/loader.ts): `apps/cli/src/lib/config/loader.ts`
- [Config validation](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/config/validator.ts): `apps/cli/src/lib/config/validator.ts`
- [Stack detection](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/utils/detect-framework.ts): `apps/cli/src/lib/utils/detect-framework.ts`

### Code generation

- [Service worker generator](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/sw-generator.ts): `apps/cli/src/lib/generators/sw-generator.ts`
- [Runtime file generators](https://github.com/iamsuudi/swoff/tree/main/apps/cli/src/lib/generators/file-generators): `apps/cli/src/lib/generators/file-generators`
- [Framework adapters](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/file-generators/generate-framework-adapters.ts): `apps/cli/src/lib/generators/file-generators/generate-framework-adapters.ts`

### Offline runtime

- [Client runtime](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/client-injector.ts): `apps/cli/src/runtime/client-injector.ts`
- [Fetch strategies](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/sw-sections/fetch-handler.ts): `apps/cli/src/lib/generators/sw-sections/fetch-handler.ts`
- [Tag invalidation](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/lib/generators/sw-sections/tag-management.ts): `apps/cli/src/lib/generators/sw-sections/tag-management.ts`
- [Mutation queue](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/mutation-queue.ts): `apps/cli/src/runtime/mutation-queue.ts`

### App integrations

- [Framework hooks](https://github.com/iamsuudi/swoff/blob/main/apps/cli/templates/react/useSwoffFetch.tsx): `apps/cli/templates/react/useSwoffFetch.tsx`
- [Storage utilities](https://github.com/iamsuudi/swoff/blob/main/apps/cli/src/runtime/storage.ts): `apps/cli/src/runtime/storage.ts`
- **PWA asset generator**

### Other components

- **App developer**
- **Swoff config**
- **Generated project files**
- **Web application**
- **Browser Cache API**
- **IndexedDB**
- **Application server**
- **Push or SSE server**
- **PWA assets**

## Connections

- App developer → CLI entry: runs
- App developer → Swoff config: configures
- CLI entry → CLI commands: dispatches
- CLI commands → Config loading: loads
- CLI commands → Config validation: validates
- Swoff config → Config loading: read by
- CLI commands → Stack detection: detects stack
- CLI commands → Service worker generator: generates worker
- CLI commands → Runtime file generators: generates runtime
- CLI commands → Framework adapters: generates adapters
- Service worker generator → Generated project files: writes worker
- Runtime file generators → Generated project files: writes runtime
- Framework adapters → Generated project files: writes hooks
- App developer → Web application: integrates files
- Web application → Client runtime: initializes
- Client runtime → Fetch strategies: registers worker
- Fetch strategies → Browser Cache API: reads and writes
- Fetch strategies → Application server: fetches requests
- Fetch strategies → Tag invalidation: tracks tags
- Fetch strategies → Mutation queue: queues mutations
- Mutation queue → IndexedDB: persists queue
- Mutation queue → Application server: retries mutations
- Web application → Framework hooks: uses hooks
- Framework hooks → Client runtime: calls runtime
- Web application → Storage utilities: checks quota
- Push or SSE server → Fetch strategies: push events
- App developer → PWA asset generator: runs separately
- PWA asset generator → PWA assets: generates assets