# swifweb/web architecture

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

- Interactive diagram: https://gitdiagram.com/swifweb/web
- Repository: https://github.com/swifweb/web

## Overview

##### Project type and purpose
- This is an open-source Swift library (“SwifWeb”) exposing the DOM, CSS, and virtually every modern Web API to Swift developers, plus a lightweight SPA/PWA framework for building web applications.
- It is not a standalone service but a layered library intended to be consumed (via Swift Package Manager) by user projects and orchestrated by the companion CLI tool “webber.”

##### File structure
- Top-level Packaging:
- Package.swift, README.md, LICENSE, .gitignore
- “Sources/” contains all Swift modules, grouped by functionality:
- WebFoundation – low-level JS/Web interop primitives, URL, Blob, State, Console, etc.
- Individual Web API wrappers – e.g. DOM, CSS, FetchAPI, WebSocketAPI, StorageAPI, ServiceWorker, CanvasAPI, GeolocationAPI, etc.
- Web – the high-level SPA/PWA framework (AppBuilder, Controllers, Routing, Pages, Middleware, WebApp, etc.)
- Worker/WorkersAPI – wrappers for Worker/SharedWorker APIs
- “Tests/” holds unit tests for ServiceWorker and Web modules.

##### README
- Confirms library purpose: “build your awesome reactive web app in beloved Swift”
- Mentions CLI workflow: `webber new`, `webber serve`, `webber release`

##### Components
a. Foundation layer (“WebFoundation”)
b. API wrapper layer (grouped functional modules: DOM, CSS, FetchAPI, Events, StorageAPI, ServiceWorker, WebSocketAPI, etc.)
c. Framework layer (“Web” module – AppBuilder, Controllers, Routing, Pages, Middleware)
d. Orchestration/CLI (“webber” tool, `.webber` folder)
e. Tests (indicate where tests plug in)
f. User-facing applications that consume the library (i.e. SPA / PWA projects generated by webber)

##### Relationships and interactions
- Tests connect to the modules they verify.

##### Architectural patterns & design principles
- Layered Architecture: clear separation of concerns from low-level interop to high-level app constructs.
- Modular design: each Web API lives in its own module, promoting extensibility.
- MVC-like in the “Web” framework: Controllers, Views (DOM/CSS builders), Routing.
- Dependency Inversion: high-level modules depend on abstract protocols in lower layers.

##### Relevant technologies
- Swift 5.7
- Swift Package Manager (Package.swift)
- Browser JavaScript engine (JSValuable, JSClass in WebFoundation)
- Command-line tool “webber” (not in this repo, but referenced)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    Browser["Browser Runtime<br/>(Web APIs in JS engine)"]:::external
    Foundation["WebFoundation<br/>(JS-Swift bridge)"]:::foundation
    subgraph "API Wrappers"
        direction TB
        DOM["DOM"]:::api
        CSS["CSS"]:::api
        FetchAPI["FetchAPI"]:::api
        Events["Events"]:::api
        DOMEvents["DOMEvents"]:::api
        StorageAPI["StorageAPI"]:::api
        ServiceWorker["ServiceWorker"]:::api
        WebSocketAPI["WebSocketAPI"]:::api
        CanvasAPI["CanvasAPI"]:::api
        GeolocationAPI["GeolocationAPI"]:::api
        WorkersAPI["WorkersAPI"]:::api
    end
    subgraph "Web Framework"
        direction TB
        WebFramework["Web<br/>(AppBuilder, Controllers, Routing, Pages, Middleware, WebApp)"]:::framework
        AppBuilder["AppBuilder"]:::framework
        Controllers["Controllers"]:::framework
        Routing["Routing"]:::framework
        Pages["Pages"]:::framework
        Middleware["Middleware"]:::framework
        WebApp["WebApp"]:::framework
    end
    WebberCLI["webber (CLI)"]:::cli
    UserApp["User SPA/PWA Project"]:::external
    subgraph "Tests"
        direction TB
        SWTests["ServiceWorkerTests"]:::tests
        WebTests["WebTests"]:::tests
    end

    %% Relationships
    Browser -->|"native API calls"| Foundation
    Foundation --> DOM
    Foundation --> CSS
    Foundation --> FetchAPI
    Foundation --> Events
    Foundation --> DOMEvents
    Foundation --> StorageAPI
    Foundation --> ServiceWorker
    Foundation --> WebSocketAPI
    Foundation --> CanvasAPI
    Foundation --> GeolocationAPI
    Foundation --> WorkersAPI

    DOM --> WebFramework
    CSS --> WebFramework
    FetchAPI --> WebFramework
    Events --> WebFramework
    DOMEvents --> WebFramework
    StorageAPI --> WebFramework
    ServiceWorker --> WebFramework
    WebSocketAPI --> WebFramework
    CanvasAPI --> WebFramework
    GeolocationAPI --> WebFramework
    WorkersAPI --> WebFramework

    WebFramework --> AppBuilder
    WebFramework --> Controllers
    WebFramework --> Routing
    WebFramework --> Pages
    WebFramework --> Middleware
    WebFramework --> WebApp

    WebFramework -->|"runtime & build time dependency"| UserApp
    WebberCLI -->|"scaffolds / serves / releases"| WebFramework
    WebberCLI -->|"scaffolds / serves / releases"| UserApp

    SWTests -.->|"tests"| ServiceWorker
    WebTests -.->|"tests"| WebFramework

    %% Click Events
    click Foundation "https://github.com/swifweb/web/tree/master/Sources/WebFoundation/"
    click DOM "https://github.com/swifweb/web/tree/master/Sources/DOM/"
    click CSS "https://github.com/swifweb/web/tree/master/Sources/CSS/"
    click FetchAPI "https://github.com/swifweb/web/tree/master/Sources/FetchAPI/"
    click Events "https://github.com/swifweb/web/tree/master/Sources/Events/"
    click DOMEvents "https://github.com/swifweb/web/tree/master/Sources/DOMEvents/"
    click StorageAPI "https://github.com/swifweb/web/tree/master/Sources/StorageAPI/"
    click ServiceWorker "https://github.com/swifweb/web/tree/master/Sources/ServiceWorker/"
    click WebSocketAPI "https://github.com/swifweb/web/tree/master/Sources/WebSocketAPI/"
    click CanvasAPI "https://github.com/swifweb/web/tree/master/Sources/CanvasAPI/"
    click GeolocationAPI "https://github.com/swifweb/web/tree/master/Sources/GeolocationAPI/"
    click WorkersAPI "https://github.com/swifweb/web/tree/master/Sources/WorkersAPI/"
    click AppBuilder "https://github.com/swifweb/web/blob/master/Sources/Web/AppBuilder.swift"
    click Controllers "https://github.com/swifweb/web/tree/master/Sources/Web/Controllers/"
    click Routing "https://github.com/swifweb/web/tree/master/Sources/Web/Routing/"
    click Pages "https://github.com/swifweb/web/tree/master/Sources/Web/Pages/"
    click Middleware "https://github.com/swifweb/web/tree/master/Sources/Web/Middleware/"
    click WebApp "https://github.com/swifweb/web/blob/master/Sources/Web/WebApp.swift"
    click WebberCLI "https://github.com/swifweb/web/tree/master/Sources/Web/WebberPreview/"
    click SWTests "https://github.com/swifweb/web/tree/master/Tests/ServiceWorkerTests/"
    click WebTests "https://github.com/swifweb/web/tree/master/Tests/WebTests/"

    %% Styles
    classDef foundation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#90EE90,stroke:#333,stroke-width:1px
    classDef framework fill:#FFA500,stroke:#333,stroke-width:1px
    classDef cli fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#EEE,stroke:#333,stroke-width:1px
    classDef tests fill:#ECECEC,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px
```
