# swiftfiddle/swiftfiddle-web architecture

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

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

## Overview

##### Project Type & Purpose
- Full-stack web application (an online Swift playground).
- Frontend: static assets built with Webpack, served under Public/.
- Backend: Swift (Vapor-style) HTTP server under Sources/App.
- Persistence: Firestore (via Google Cloud) + GitHub Gist integration.
- CI/CD: GitHub Actions + Docker.

##### File Structure
Top-level:
- Public/ — HTML/CSS/JS assets, embedded playground code (client).
- Sources/App/ — Swift server: configure.swift, routes.swift, entrypoint.swift.
– Controllers (API handlers for compilation, sharing, fetching, etc.)
– Middlewares (error handling, headers)
– Models (request/response DTOs)
- webpack.*.js — build pipelines for dev/prod.
- Dockerfile, .github/workflows — containerization & CI/CD.
- Dependencies: Package.swift (SwiftPM), package.json (npm).

##### README for Insights
- Purpose: share/embed/run Swift code in browser.
- Tech stack: Swift 5.9, macOS/Linux, MIT licensed.
- Related: external SwiftLSP service for code-completion.

##### Main Components & Interactions
a. Frontend (Browser)
– UI: editor, buttons, version picker (Public/js/*.js).
– Runner: Web Worker (Public/js/worker.js) compiles & executes in-browser or requests server.
– LSP client: Public/js/language_server.js connects to language-server endpoint.
– Embedded view: Public/embedded.html/embedded.js for iframes.

b. Backend Server (Vapor-style)
– HTTP API endpoints (Sources/App/Controllers/*).
– Routes configured in routes.swift.
– Middlewares for error & custom headers.
– Services:
- Firestore (Controllers/Firestore.swift) for persistence.
- GitHub Gist API (Controllers/Gist.swift).
- SharedImage generation (Controllers/ShareImage.swift).
- SharedLink handling (Controllers/SharedLink.swift).
- SwiftPackage info (Controllers/SwiftPackage.swift).

c. Data Stores & External Services
– Firestore (Google Cloud)
– GitHub API
– Optional: Language server (external SwiftFiddle-LSP or SourceKit-LSP).

d. CI/CD & Deployment
– Dockerized server + Nginx (implied)
– GitHub Actions build/test/deploy pipelines.

##### Architectural Patterns & Principles
- MVC-style controllers + models on server.
- Middleware pipeline for cross-cutting concerns.
- SPA front-end served as static assets.
- Build separation: Webpack for JS/CSS, SwiftPM for server code.
- Externalized configuration (swiftpm, package.json, webpack configs).

- Browser (Client)
- Web Server (SwiftFiddle Backend)
- Database & External Services
- CI/CD Pipeline
– Static Assets (HTML/CSS/JS)
– Web Worker (code execution)
– LSP Client
– HTTP API Layer (routes + controllers)
– Middlewares
– Models
– Business Logic (share, gist, compile package)
– Firestore
– GitHub Gist API
– (Optionally) Language Server
– GitHub Actions workflows
– Docker build & deploy

##### Final Checklist
– All components from Public/, Sources/App/, external services represented.
– Build & deployment pipeline nodes.
– Clear annotations of frameworks: Webpack, SwiftPM (Vapor), Firestore SDK, GitHub API.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Browser (Client)
    subgraph "Browser (Client)"
        direction TB
        StaticAssets["Static Assets (HTML/CSS/JS)"]:::client
        CSS["CSS Files"]:::client
        JSBundle["JavaScript Bundle (app.js)"]:::client
        WebWorker["Web Worker (worker.js)"]:::client
        LSPClient["LSP Client (language_server.js)"]:::client
        EmbeddedHTML["Embedded View HTML"]:::client
        EmbeddedJS["Embedded View JS"]:::client
        VersionPickerJS["Version Picker JS"]:::client
        VersionPickerCSS["Version Picker CSS"]:::client
        ShareSheetJS["Share Sheet JS"]:::client
        ShareSheetCSS["Share Sheet CSS"]:::client
        ErrorPage["Error Page (error.html)"]:::client
    end

    %% Web Server (Backend)
    subgraph "Web Server (SwiftFiddle Backend)"
        direction TB
        Entrypoint["Entrypoint"]:::server
        Configure["Configuration"]:::server
        Routes["HTTP Routes"]:::server
        subgraph "Middlewares"
            direction TB
            ErrorMiddleware["CommonErrorMiddleware"]:::server
            HeaderMiddleware["CustomHeaderMiddleware"]:::server
        end
        subgraph "Controllers"
            direction TB
            FirestoreCtrl["Firestore Controller"]:::server
            GistCtrl["GitHub Gist Controller"]:::server
            ShareImageCtrl["ShareImage Controller"]:::server
            SharedLinkCtrl["SharedLink Controller"]:::server
            SwiftPackageCtrl["SwiftPackage Controller"]:::server
            Base32["Base32 Utility"]:::server
        end
        subgraph "Models"
            direction TB
            ExecReq["ExecutionRequestParameter"]:::server
            ExecResp["ExecutionResponse"]:::server
            EmbeddedResp["EmbeddedPageResponse"]:::server
            InitialResp["InitialPageResponse"]:::server
            SharedLinkReq["SharedLinkRequestParameter"]:::server
            PackageInfo["PackageInfo"]:::server
            VersionGroup["VersionGroup"]:::server
            FoldRange["FoldRange"]:::server
        end
        Versions["Version Management"]:::server
    end

    %% External Services
    subgraph "Database & External Services"
        direction TB
        FirestoreDB["Firestore (Database)"]:::external
        GitHubAPI["GitHub Gist API"]:::external
        LanguageServer["Language Server (LSP)"]:::external
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CIWorkflows["GitHub Actions Workflows"]:::ci
        DockerfileNode["Dockerfile"]:::ci
        PackageSwiftNode["Package.swift"]:::ci
        PackageResolvedNode["Package.resolved"]:::ci
        WebpackCommon["webpack.common.js"]:::ci
        WebpackDev["webpack.dev.js"]:::ci
        WebpackProd["webpack.prod.js"]:::ci
        PackageJSON["package.json"]:::ci
        PackageLock["package-lock.json"]:::ci
    end

    %% Connections
    StaticAssets -->|serves assets| JSBundle
    StaticAssets --> CSS
    JSBundle --> WebWorker
    JSBundle --> LSPClient
    JSBundle --> VersionPickerJS
    JSBundle --> ShareSheetJS
    StaticAssets --> ErrorPage
    JSBundle --> EmbeddedJS
    JSBundle --> EmbeddedHTML

    WebWorker -->|POST /execute| Entrypoint
    VersionPickerJS -->|GET /versions| Versions
    ShareSheetJS -->|POST /share| SharedLinkCtrl
    EmbeddedJS -->|GET /embed| EmbeddedResp

    Entrypoint --> Configure
    Configure --> Routes
    Routes --> ErrorMiddleware
    Routes --> HeaderMiddleware
    Routes --> FirestoreCtrl
    Routes --> GistCtrl
    Routes --> ShareImageCtrl
    Routes --> SharedLinkCtrl
    Routes --> SwiftPackageCtrl

    FirestoreCtrl -->|read/write| FirestoreDB
    GistCtrl -->|via REST| GitHubAPI
    LSPClient <-->|LSP| LanguageServer

    Routes --> ExecReq
    ExecReq --> ExecResp
    SharedLinkCtrl --> SharedLinkReq
    SwiftPackageCtrl --> PackageInfo
    SwiftPackageCtrl --> VersionGroup
    ShareImageCtrl --> FoldRange

    CIWorkflows --> DockerfileNode
    CIWorkflows --> WebpackCommon
    CIWorkflows --> WebpackDev
    CIWorkflows --> WebpackProd
    CIWorkflows --> PackageSwiftNode
    CIWorkflows --> PackageResolvedNode
    CIWorkflows --> PackageJSON
    CIWorkflows --> PackageLock
    DockerfileNode -->|builds container| Entrypoint

    %% Click Events
    click StaticAssets "https://github.com/swiftfiddle/swiftfiddle-web/tree/master/Public/"
    click CSS "https://github.com/swiftfiddle/swiftfiddle-web/tree/master/Public/css/"
    click JSBundle "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/js/app.js"
    click WebWorker "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/js/worker.js"
    click LSPClient "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/js/language_server.js"
    click EmbeddedHTML "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/embedded.html"
    click EmbeddedJS "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/embedded.js"
    click VersionPickerJS "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/js/version_picker.js"
    click VersionPickerCSS "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/css/version_picker.css"
    click ShareSheetJS "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/js/share_sheet.js"
    click ShareSheetCSS "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/css/share_sheet.css"
    click ErrorPage "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Public/error.html"
    click Entrypoint "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/entrypoint.swift"
    click Configure "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/configure.swift"
    click Routes "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/routes.swift"
    click ErrorMiddleware "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Middlewares/CommonErrorMiddleware.swift"
    click HeaderMiddleware "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Middlewares/CustomHeaderMiddleware.swift"
    click FirestoreCtrl "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Controllers/Firestore.swift"
    click GistCtrl "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Controllers/Gist.swift"
    click ShareImageCtrl "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Controllers/ShareImage.swift"
    click SharedLinkCtrl "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Controllers/SharedLink.swift"
    click SwiftPackageCtrl "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Controllers/SwiftPackage.swift"
    click Base32 "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Controllers/Base32.swift"
    click ExecReq "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/ExecutionRequestParameter.swift"
    click ExecResp "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/ExecutionResponse.swift"
    click EmbeddedResp "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/EmbeddedPageResponse.swift"
    click InitialResp "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/InitialPageResponse.swift"
    click SharedLinkReq "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/SharedLinkRequestParameter.swift"
    click PackageInfo "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/PackageInfo.swift"
    click VersionGroup "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/VersionGroup.swift"
    click FoldRange "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/Models/FoldRange.swift"
    click Versions "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Sources/App/versions.swift"
    click CIWorkflows "https://github.com/swiftfiddle/swiftfiddle-web/tree/master/.github/workflows/"
    click DockerfileNode "https://github.com/swiftfiddle/swiftfiddle-web/tree/master/Dockerfile"
    click PackageSwiftNode "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Package.swift"
    click PackageResolvedNode "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/Package.resolved"
    click WebpackCommon "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/webpack.common.js"
    click WebpackDev "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/webpack.dev.js"
    click WebpackProd "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/webpack.prod.js"
    click PackageJSON "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/package.json"
    click PackageLock "https://github.com/swiftfiddle/swiftfiddle-web/blob/master/package-lock.json"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef server fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef ci fill:#e2e3e5,stroke:#333,stroke-width:1px
```
