# pointfreeco/isowords architecture

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

- Interactive diagram: https://gitdiagram.com/pointfreeco/isowords
- Repository: https://github.com/pointfreeco/isowords

## Overview

##### Main components
- Shared Modules: These include common models and logic used by both client and server. For example, modules like ClientModels, SharedModels, and various “Helpers” (e.g. DateHelpers, TcaHelpers, etc.) that implement game logic, puzzles, and state management.
- External Services & Dependencies: Indicate external APIs and services leveraged by the app (for example, GameCenter, StoreKit, Push Notifications, and even third-party libraries like SnapshotTesting). Also add the automated App Store screenshots and preview generation (taken from tests).

##### Relationships and interactions
- Shared logic is used on both ends—for example, the same types defined in SharedModels and ClientModels are used in serialization/deserialization for API communication.
- Within the client, highlight the Composable Architecture: the Store, Reducers, and Effects. Show that different feature modules (game states, onboarding, leaderboards, etc.) communicate via state mutations and dependency injection.
- That many modules are independently testable as seen by the extensive Tests folder, including snapshots and integration tests that span both client and server.

##### Architectural patterns and design principles
- Composable Architecture (single source of truth; reducers composed from many child reducers).
- Hyper-modularization: Each feature is isolated in its own module (e.g., Sources/ActiveGamesFeature, Sources/GameOverFeature, Sources/VocabFeature, etc.). Emphasize that dependencies are explicit and module boundaries are maintained.
- Shared monorepo for client and server: Emphasize that there is a single code base “client/server monorepo” where common code is shared between both the front-end and back-end.
- Clear separation between UI (built in SwiftUI/SceneKit) and business logic.

##### Relevant technologies and frameworks
- Swift (the language in which everything is written).
- SwiftUI and SceneKit (UI components).
- The Composable Architecture (for structuring state and effects).
- Swift Package Manager (the Package.swift files at the top level and in modules tie everything together).
- Testing frameworks (SnapshotTesting, and various unit/integration tests).
- Server libraries provided by Point-Free for building the Swift-based server.

## Diagram (Mermaid)

```mermaid
graph TD
    %% iOS Client Subgraph
    subgraph "iOS Client"
        direction TB
        ClientUI["iOS Client: App (SwiftUI/SceneKit)"]:::ui
        ClientPreviews["App Previews"]:::ui
        ComposableArch["Composable Architecture\n(Store, Reducers, Effects)"]:::logic
        subgraph "Feature Modules"
            direction TB
            AppFeature["App Feature"]:::logic
            GameFeature["Game Feature"]:::logic
            HomeFeature["Home Feature"]:::logic
            LeaderboardFeature["Leaderboard Feature"]:::logic
            DailyChallengeFeature["Daily Challenge Feature"]:::logic
            GameOverFeature["Game Over Feature"]:::logic
            MultiplayerFeature["Multiplayer Feature"]:::logic
        end
        Resources["Resources/Assets & Config"]:::resources
    end

    %% Server Subgraph
    subgraph "Server"
        direction TB
        ServerEntry["Server Entry"]:::server
        ServerRunner["Server Runner"]:::server
        ServerConfig["Server Config"]:::server
        ServerRouter["Server Router (API)"]:::server
        subgraph "Middleware"
            direction TB
            SiteMiddleware["Site Middleware"]:::middleware
            ServerConfigMiddleware["Server Config Middleware"]:::middleware
            PushMiddleware["Push Middleware"]:::middleware
            ShareGameMiddleware["Share Game Middleware"]:::middleware
            VerifyReceiptMiddleware["Verify Receipt Middleware"]:::middleware
        end
        Database["Database/External Service"]:::database
    end

    %% Shared Modules Subgraph
    subgraph "Shared Modules"
        direction TB
        ClientModels["Client Models"]:::shared
        SharedModels["Shared Models"]:::shared
        TcaHelpers["TCA Helpers"]:::shared
        DateHelpers["Date Helpers"]:::shared
        SwiftUIHelpers["SwiftUI Helpers"]:::shared
        Styleguide["Styleguide"]:::shared
    end

    %% External Services Subgraph
    subgraph "External Services"
        direction TB
        ComposableGameCenter["Composable GameCenter"]:::external
        ComposableStoreKit["Composable StoreKit"]:::external
        RemoteNotifications["Remote Notifications Client"]:::external
        UIApplicationClient["UIApplication Client"]:::external
    end

    %% Testing Frameworks
    Tests["Automated Tests\n(Snapshot, Unit/Integration)"]:::test
    AppStoreSnapshotTests["App Store Snapshot Tests"]:::test

    %% Connections within iOS Client
    ClientUI -->|"initializes"| ClientPreviews
    ClientUI -->|"manages"| ComposableArch
    ComposableArch -->|"composes"| AppFeature
    ComposableArch -->|"composes"| GameFeature
    ComposableArch -->|"composes"| HomeFeature
    ComposableArch -->|"composes"| LeaderboardFeature
    ComposableArch -->|"composes"| DailyChallengeFeature
    ComposableArch -->|"composes"| GameOverFeature
    ComposableArch -->|"composes"| MultiplayerFeature
    ComposableArch -->|"utilizes"| Resources

    %% Connections from Client to Server and Shared Modules
    ComposableArch ---|"API_Calls"| ServerRouter
    ComposableArch ---|"shares_data"| ClientModels
    ComposableArch ---|"shares_data"| SharedModels
    ClientModels ---|"common_logic"| SharedModels
    TcaHelpers ---|"support"| ComposableArch
    DateHelpers ---|"support"| ComposableArch
    SwiftUIHelpers ---|"support"| ClientUI

    %% Connections within the Server
    ServerEntry --> ServerRunner
    ServerRunner --> ServerConfig
    ServerConfig --> ServerRouter
    ServerRouter -->|"routes"| SiteMiddleware
    ServerRouter -->|"routes"| ServerConfigMiddleware
    ServerRouter -->|"routes"| PushMiddleware
    ServerRouter -->|"routes"| ShareGameMiddleware
    ServerRouter -->|"routes"| VerifyReceiptMiddleware
    ServerRouter -->|"data_access"| Database

    %% Connections between Shared Modules and Server
    SharedModels ---|"serialization"| ServerRouter

    %% Connections with External Services
    ComposableArch ---|"integrates"| ComposableGameCenter
    ComposableArch ---|"integrates"| ComposableStoreKit
    ServerRouter ---|"external_calls"| RemoteNotifications
    ServerRouter ---|"external_calls"| UIApplicationClient

    %% Connections for Tests
    Tests ---|"verifies"| ComposableArch
    Tests ---|"verifies"| ServerRouter
    AppStoreSnapshotTests ---|"captures_UI"| ClientPreviews

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef logic fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef resources fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef server fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef middleware fill:#EDBB99,stroke:#CB4335,stroke-width:2px;
    classDef database fill:#C39BD3,stroke:#8E44AD,stroke-width:2px;
    classDef shared fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef test fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;

    %% Click Events for iOS Client Components
    click ClientUI "https://github.com/pointfreeco/isowords/tree/main/App/iOS"
    click ClientPreviews "https://github.com/pointfreeco/isowords/tree/main/App/Previews"

    %% Click Events for Client Feature Modules
    click AppFeature "https://github.com/pointfreeco/isowords/tree/main/Sources/AppFeature"
    click GameFeature "https://github.com/pointfreeco/isowords/tree/main/Sources/GameFeature"
    click HomeFeature "https://github.com/pointfreeco/isowords/tree/main/Sources/HomeFeature"
    click LeaderboardFeature "https://github.com/pointfreeco/isowords/tree/main/Sources/LeaderboardFeature"
    click DailyChallengeFeature "https://github.com/pointfreeco/isowords/tree/main/Sources/DailyChallengeFeature"
    click GameOverFeature "https://github.com/pointfreeco/isowords/tree/main/Sources/GameOverFeature"
    click MultiplayerFeature "https://github.com/pointfreeco/isowords/tree/main/Sources/MultiplayerFeature"

    %% Click Events for Shared Modules
    click ClientModels "https://github.com/pointfreeco/isowords/tree/main/Sources/ClientModels"
    click SharedModels "https://github.com/pointfreeco/isowords/tree/main/Sources/SharedModels"
    click TcaHelpers "https://github.com/pointfreeco/isowords/tree/main/Sources/TcaHelpers"
    click DateHelpers "https://github.com/pointfreeco/isowords/tree/main/Sources/DateHelpers"
    click SwiftUIHelpers "https://github.com/pointfreeco/isowords/tree/main/Sources/SwiftUIHelpers"
    click Styleguide "https://github.com/pointfreeco/isowords/tree/main/Sources/Styleguide"

    %% Click Events for Server Components
    click ServerEntry "https://github.com/pointfreeco/isowords/tree/main/Sources/server"
    click ServerRunner "https://github.com/pointfreeco/isowords/tree/main/Sources/runner"
    click ServerConfig "https://github.com/pointfreeco/isowords/tree/main/Sources/ServerConfig"
    click ServerRouter "https://github.com/pointfreeco/isowords/tree/main/Sources/ServerRouter"
    click SiteMiddleware "https://github.com/pointfreeco/isowords/tree/main/Sources/SiteMiddleware"
    click ServerConfigMiddleware "https://github.com/pointfreeco/isowords/tree/main/Sources/ServerConfigMiddleware"
    click PushMiddleware "https://github.com/pointfreeco/isowords/tree/main/Sources/PushMiddleware"
    click ShareGameMiddleware "https://github.com/pointfreeco/isowords/tree/main/Sources/ShareGameMiddleware"
    click VerifyReceiptMiddleware "https://github.com/pointfreeco/isowords/tree/main/Sources/VerifyReceiptMiddleware"

    %% Click Events for External Services
    click ComposableGameCenter "https://github.com/pointfreeco/isowords/tree/main/Sources/ComposableGameCenter"
    click ComposableStoreKit "https://github.com/pointfreeco/isowords/tree/main/Sources/ComposableStoreKit"
    click RemoteNotifications "https://github.com/pointfreeco/isowords/tree/main/Sources/RemoteNotificationsClient"
    click UIApplicationClient "https://github.com/pointfreeco/isowords/tree/main/Sources/UIApplicationClient"

    %% Click Event for Testing Framework
    click AppStoreSnapshotTests "https://github.com/pointfreeco/isowords/tree/main/Tests/AppStoreSnapshotTests"
```
