# wikipediabrown/napkin architecture

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

- Interactive diagram: https://gitdiagram.com/wikipediabrown/napkin
- Repository: https://github.com/wikipediabrown/napkin

## Overview

##### Project’s type and purpose
- **Type**: Open-source Swift Package + Xcode template repository
- **Purpose**:
– Provide a modular RIBs-style architecture (Builder, Router, Interactor, Presenter, DI) for Swift apps
– Supply Xcode file templates and an install script for rapid component generation
– Automate CI/CD (tests + releases) via GitHub Actions and Fastlane

##### File structure
- **Sources/napkin** – core framework code, subdivided into:
– Builder & ComponentizedBuilder modules (assembly of components)
– DI sub-module (Component, Dependency protocols)
– Interactor, PresentableInteractor (business logic)
– Router, LaunchRouter, ViewableRouter (navigation & view ownership)
– Presenter, ViewControllable (view-layer abstraction)
– LeakDetection (Executor, LeakDetector) – optional runtime leak hooks
– MultiStageComponentizedBuilder (advanced builder)
- **Tools/napkin** – Xcode template files + InstallXcodeTemplates.sh
- **Tests/** – unit tests for framework
- **.github/workflows** – CI pipelines for Tests, ReleaseTests, Release
- **fastlane/** – Fastlane configuration (unit_test lane)
- **Package.swift**, Gemfile – package & dependency management

##### Extract architecture hints from the README
- Uses Swift Package Manager, Combine instead of RxSwift
- Integrates with Xcode via custom file templates
- CI: GitHub Actions + Fastlane
- No external servers or databases—pure client-side library

##### Main components
A. **Core Framework Module (napkin)**
- Builder
- ComponentizedBuilder / MultiStageComponentizedBuilder
- DI system (Component, Dependency)
- Interactor / PresentableInteractor
- Router / LaunchRouter / ViewableRouter
- Presenter / ViewControllable
- LeakDetection (Executor, LeakDetector)
B. **Xcode Template Tooling**
- InstallXcodeTemplates.sh (CLI script)
- Template bundles under Tools/napkin (Launch, Component Extension, Service Manager, Unit Tests)
C. **Testing Suite**
- XCTest targets under Tests/napkinTests
D. **CI/CD Pipelines**
- GitHub Actions workflows (Tests.yml, ReleaseTests.yml, Release.yml)
- fastlane unit_test lane

##### Relationships & data flows
- **At runtime (client app + napkin library)**:
- App invokes **Builder** → constructs **Component** graph via DI
- **Router** created by Builder → attaches **Interactor** + optional **Presenter**
- **Interactor** executes business logic, calls into **Presenter** → updates **ViewControllable**
- **LeakDetector** optionally monitors objects—communicates with **Executor**
- **At development time**:
- Developer runs **InstallXcodeTemplates.sh** → copies Templates to Xcode
- In Xcode: “New File” → custom napkin templates generate boilerplate Builder/Interactor/Router/View code
- **At CI/CD time**:
- Push to repo → GitHub Actions triggers **Tests** → builds & runs unit tests
- Merged release branch → triggers **ReleaseTests** + **Release** workflow
- fastlane can be invoked locally for multi-platform test runs

##### Architectural patterns & principles
- **Modularization** via RIBs-style components (single-responsibility modules)
- **Dependency Injection** (Component/Dependency protocols)
- **Separation of Concerns**: Builders (assembly), Interactors (business logic), Routers (navigation), Presenters (view logic), Views (UI)
- **Extensibility**: Multi-stage builders, customizable templates

##### Elements
- **Clear labels** on each major block and sub-block
– Builder → Component → Router → Interactor → Presenter → View
– Install script → Xcode → generated files
– CI trigger → workflows → test suites → release
– Rectangles for code modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    Pkg["Package.swift"]:::entry

    %% Core Framework Modules
    subgraph "Core Framework (napkin)"
        direction TB
        subgraph "DI Module"
            direction TB
            ComponentProto["Component Protocol"]:::core
            DependencyProto["Dependency Protocol"]:::core
        end
        subgraph "Builder Modules"
            direction TB
            Builder["Builder"]:::core
            CompBuilder["ComponentizedBuilder"]:::core
            MultiStageBuilder["MultiStageComponentizedBuilder"]:::core
        end
        subgraph "RIB Components"
            direction TB
            subgraph "Interactors"
                Interactor["Interactor"]:::core
                PresentableInteractor["PresentableInteractor"]:::core
            end
            subgraph "Routers"
                Router["Router"]:::core
                LaunchRouter["LaunchRouter"]:::core
                ViewableRouter["ViewableRouter"]:::core
            end
            subgraph "Presenters"
                Presenter["Presenter"]:::core
                ViewControllable["ViewControllable"]:::core
            end
        end
        subgraph "Leak Detection"
            direction TB
            Executor["Executor"]:::core
            LeakDetector["LeakDetector"]:::core
        end
    end

    %% Developer Tooling
    subgraph "Xcode Template Tooling"
        direction TB
        InstallScript["InstallXcodeTemplates.sh"]:::tool
        Templates["Template Bundles"]:::tool
        Xcode["Xcode"]:::external
    end

    %% Testing Suite
    subgraph "Testing Suite"
        direction TB
        LinuxMain["LinuxMain.swift"]:::test
        XCTestManifests["XCTestManifests.swift"]:::test
        NapkinTests["napkinTests.swift"]:::test
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        GitPush["GitHub Push"]:::external
        TestsWF["Tests.yml"]:::ci
        ReleaseTestsWF["ReleaseTests.yml"]:::ci
        ReleaseWF["Release.yml"]:::ci
        Fastlane["Fastfile (fastlane)"]:::ci
    end

    %% Runtime Data Flow (solid arrows)
    Pkg -->|builds package| Builder
    Builder -->|uses| ComponentProto
    Builder -->|uses| DependencyProto
    Builder -->|creates| Router
    Router -->|attaches| Interactor
    Interactor -->|calls| Presenter
    Presenter -->|updates| ViewControllable
    LeakDetector -->|monitors via| Executor

    %% Development Time Flow (dashed arrows)
    InstallScript -.->|copies templates| Templates
    Templates -.->|available in| Xcode
    Xcode -.->|generate files| Builder

    %% CI/CD Flow (dotted arrows)
    GitPush -.->|trigger| TestsWF
    TestsWF -.->|runs| LinuxMain
    TestsWF -.->|runs| XCTestManifests
    TestsWF -.->|runs| NapkinTests
    GitPush -.->|on merge| ReleaseTestsWF
    ReleaseTestsWF -.->|validates release| ReleaseWF
    Fastlane -.->|local test lane| NapkinTests

    %% Click Events
    click Builder "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/Builder.swift"
    click CompBuilder "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/ComponentizedBuilder.swift"
    click MultiStageBuilder "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/MultiStageComponentizedBuilder.swift"
    click ComponentProto "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/DI/Component.swift"
    click DependencyProto "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/DI/Dependency.swift"
    click Interactor "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/Interactor.swift"
    click PresentableInteractor "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/PresentableInteractor.swift"
    click Router "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/Router.swift"
    click LaunchRouter "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/LaunchRouter.swift"
    click ViewableRouter "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/ViewableRouter.swift"
    click Presenter "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/Presenter.swift"
    click ViewControllable "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/ViewControllable.swift"
    click Executor "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/LeakDetection/Executor.swift"
    click LeakDetector "https://github.com/wikipediabrown/napkin/blob/develop/Sources/napkin/LeakDetection/LeakDetector.swift"
    click InstallScript "https://github.com/wikipediabrown/napkin/blob/develop/Tools/InstallXcodeTemplates.sh"
    click Templates "https://github.com/wikipediabrown/napkin/tree/develop/Tools/napkin/"
    click LinuxMain "https://github.com/wikipediabrown/napkin/blob/develop/Tests/LinuxMain.swift"
    click XCTestManifests "https://github.com/wikipediabrown/napkin/blob/develop/Tests/napkinTests/XCTestManifests.swift"
    click NapkinTests "https://github.com/wikipediabrown/napkin/blob/develop/Tests/napkinTests/napkinTests.swift"
    click TestsWF "https://github.com/wikipediabrown/napkin/blob/develop/.github/workflows/Tests.yml"
    click ReleaseTestsWF "https://github.com/wikipediabrown/napkin/blob/develop/.github/workflows/ReleaseTests.yml"
    click ReleaseWF "https://github.com/wikipediabrown/napkin/blob/develop/.github/workflows/Release.yml"
    click Fastlane "https://github.com/wikipediabrown/napkin/tree/develop/fastlane/Fastfile"

    %% Styles
    classDef entry fill:#E2E2E2,stroke:#333,stroke-width:1px
    classDef core fill:#B3DFFF,stroke:#1A5A96,stroke-width:1px
    classDef tool fill:#C6F6D5,stroke:#2F855A,stroke-width:1px
    classDef test fill:#E9D8FD,stroke:#6B46C1,stroke-width:1px
    classDef ci fill:#FEEBC8,stroke:#DD6B20,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
