# swiftfiddle/swiftfiddle-formatter architecture

> Architecture diagram of the GitHub repository swiftfiddle/swiftfiddle-formatter, 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-formatter
- Repository: https://github.com/swiftfiddle/swiftfiddle-formatter

## Overview

##### Project Type and Purpose
- From the README (“SwiftFiddle Formatter is a versatile playground for experimenting with swift-format … right in your browser”) and the file tree, this is a full-stack web application.
- The frontend is a single-page application (SPA) built with plain JavaScript, CSS/SCSS, HTML, and bundled by Webpack.
- The backend is a Swift-based web server (likely using Vapor or a similar Swift HTTP framework), which exposes REST endpoints to invoke the Swift formatting engine.

##### High-Level File Structure Analysis
- Public/
- Static web assets (index.html, JS modules, CSS/SCSS, images, favicons)
- webpack.{common,dev,prod}.js and package.json/lock.json at root manage JS build pipelines.
- Sources/App/
- entrypoint.swift, configure.swift, routes.swift define server startup, routing, middleware registration.
- Middlewares/ contains reusable middleware (error handling, custom headers).
- Resources/formatter/
- A Swift package that wraps or embeds the official swift-format library.
- Compiled into the application or invoked as a subprocess to perform code formatting.
- Dockerfile, fly.toml, .github/workflows/…
- Containerization and CI/CD definitions for testing, deployment, and security analysis.

##### Key Architectural Insights from README & Code
- Single endpoint (e.g., POST /format) receives Swift source + config → returns formatted code.
- No persistent storage; this is stateless and can be horizontally scaled.
- Uses SwiftPM to build both the server and the embedded formatter.
- Frontend communicates over HTTP(S) with the Swift server API.

##### Components
a. Client Layer (Browser)
- Editor UI (Public/index.html + JS modules: editor.js, defaults.js, configuration.js, etc.)
b. CDN / Static Assets Server
- Serves the bundled JS/CSS/HTML (could be same Vapor server or a separate static host)
c. Application Server (Swift/Vapor)
- HTTP listener (entrypoint.swift)
- Routing (routes.swift)
- Middleware chain (CommonErrorMiddleware, CustomHeaderMiddleware)
- FormatController (handles /format requests)
d. Formatter Engine
- Embedded swift-format library (Resources/formatter)
- Invoked as an in-process call or subprocess
e. CI/CD & Infrastructure
- Docker container orchestration (Dockerfile, fly.toml for Fly.io)
- GitHub Actions (test.yml, deploy.yml, codeql-analysis.yml)
- Optional: Load balancer, HTTPS termination
f. External Services
- GitHub (repo, sponsors)

##### Interaction Flows & Relationships
- User types Swift code in the browser editor → clicks “Format.”
- Browser sends HTTP POST /format with payload { code, config } → Application Server.
- Middleware validates request and appends headers.
- Route handler calls Formatter Engine → returns formatted code or an error.
- Server responds with JSON { formattedCode } → Browser.
- UI displays the formatted code or error in result_view.js/snackbar.js.

##### Architectural Patterns and Principles
- SPA + REST API: clear separation of concerns between presentation and business logic
- Stateless server: no database, easy horizontal scaling
- Middleware pipeline for cross-cutting concerns (error handling, headers)
- Containerized deployment ensures environment parity

##### Final Checklist
- All components labeled (Client, CDN/Static Host, Server, Engine, CI/CD, External)
- Notes on important middleware and entry points (e.g., entrypoint.swift, routes.swift)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer (Browser)" 
        direction TB
        UX["User"]:::external
        HTML["index.html"]:::frontend
        EditorJS["editor.js"]:::frontend
        DefaultsJS["defaults.js"]:::frontend
        ConfigJS["configuration.js"]:::frontend
        ResultJS["result_view.js"]:::frontend
        SnackbarJS["snackbar.js"]:::frontend
        IconJS["icon.js"]:::frontend
        DebounceJS["debounce.js"]:::frontend
        AboutJS["about.js"]:::frontend
        SwiftFmtJS["swift_format.js"]:::frontend
        CommonCSS["common.css"]:::frontend
        DefaultSCSS["default.scss"]:::frontend
    end

    %% Build & Bundling
    subgraph "Build & Bundling" 
        direction TB
        NPM["package.json & lock"]:::frontend
        WebpackCommon["webpack.common.js"]:::frontend
        WebpackDev["webpack.dev.js"]:::frontend
        WebpackProd["webpack.prod.js"]:::frontend
    end

    %% CDN / Static Host
    CDN["Static Asset Server (Public/)"]:::infra

    %% Application Server
    subgraph "Swift Server (Vapor)" 
        direction TB
        Entrypoint["entrypoint.swift"]:::backend
        Configure["configure.swift"]:::backend
        Routes["routes.swift"]:::backend
        ErrorMW["CommonErrorMiddleware.swift"]:::backend
        HeaderMW["CustomHeaderMiddleware.swift"]:::backend
    end

    %% Formatter Engine
    Formatter["Formatter Engine<br/>(Resources/formatter/)"]:::engine

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment" 
        direction TB
        Dockerfile["Dockerfile"]:::infra
        FlyToml["fly.toml"]:::infra
        DockerIgnore[".dockerignore"]:::infra
        subgraph "GitHub Workflows"
            direction TB
            TestWF["test.yml"]:::infra
            DeployWF["deploy.yml"]:::infra
            CodeQLWF["codeql-analysis.yml"]:::infra
            SPMWF["spm.yml"]:::infra
        end
    end

    %% External Services
    subgraph "External" 
        direction TB
        GitHub["GitHub"]:::external
        LoadBalancer["Load Balancer / HTTPS"]:::external
    end

    %% Flows
    UX -->|opens| HTML
    HTML -->|loads| EditorJS & DefaultsJS & ConfigJS & ResultJS & SnackbarJS & IconJS & DebounceJS & AboutJS & SwiftFmtJS & CommonCSS & DefaultSCSS
    NPM & WebpackCommon & WebpackDev & WebpackProd -->|bundle assets| CDN
    CDN -->|serves static files| HTML

    UX -->|interacts| HTML
    HTML -->|POST /format| Entrypoint
    Entrypoint -->|configure pipelines| Configure
    Configure --> Routes
    Routes -->|invokes middleware| ErrorMW & HeaderMW
    Routes -->|calls controller| Formatter
    Formatter -->|returns formatted code| Routes
    Routes -->|response JSON| HTML

    %% Deployment Flow
    TestWF & CodeQLWF -->|CI tests| Dockerfile
    Dockerfile -->|build image| FlyToml
    FlyToml -->|deploy| LoadBalancer
    LoadBalancer --> Entrypoint

    GitHub -->|hosts repo & workflows| TestWF & DeployWF & CodeQLWF & SPMWF

    %% Click Events
    click HTML "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/index.html"
    click EditorJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/editor.js"
    click DefaultsJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/defaults.js"
    click ConfigJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/configuration.js"
    click ResultJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/result_view.js"
    click SnackbarJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/snackbar.js"
    click IconJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/icon.js"
    click DebounceJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/debounce.js"
    click AboutJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/about.js"
    click SwiftFmtJS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/js/swift_format.js"
    click CommonCSS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/css/common.css"
    click DefaultSCSS "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Public/scss/default.scss"
    click NPM "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/package.json"
    click WebpackCommon "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/webpack.common.js"
    click WebpackDev "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/webpack.dev.js"
    click WebpackProd "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/webpack.prod.js"
    click CDN "https://github.com/swiftfiddle/swiftfiddle-formatter/tree/main/Public/"
    click Entrypoint "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Sources/App/entrypoint.swift"
    click Configure "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Sources/App/configure.swift"
    click Routes "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Sources/App/routes.swift"
    click ErrorMW "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Sources/App/Middlewares/CommonErrorMiddleware.swift"
    click HeaderMW "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/Sources/App/Middlewares/CustomHeaderMiddleware.swift"
    click Formatter "https://github.com/swiftfiddle/swiftfiddle-formatter/tree/main/Resources/formatter/"
    click Dockerfile "https://github.com/swiftfiddle/swiftfiddle-formatter/tree/main/Dockerfile"
    click FlyToml "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/fly.toml"
    click DockerIgnore "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/.dockerignore"
    click TestWF "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/.github/workflows/test.yml"
    click DeployWF "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/.github/workflows/deploy.yml"
    click CodeQLWF "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/.github/workflows/codeql-analysis.yml"
    click SPMWF "https://github.com/swiftfiddle/swiftfiddle-formatter/blob/main/.github/workflows/spm.yml"

    %% Styles
    classDef frontend fill:#dae8fc,stroke:#6c8ebf,color:#000;
    classDef backend fill:#d5e8d4,stroke:#82b366,color:#000;
    classDef engine fill:#ffe6cc,stroke:#d79b00,color:#000;
    classDef infra fill:#f2f2f2,stroke:#999999,color:#000;
    classDef external fill:#e1d5e7,stroke:#9673a6,color:#000;
```
