# farzaa/freewrite architecture

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

- Interactive diagram: https://gitdiagram.com/farzaa/freewrite
- Repository: https://github.com/farzaa/freewrite

## Overview

1. **Project shape**
   - This is a single macOS app built with **SwiftUI** in Xcode.
   - The repo is intentionally small: one app target, a couple of feature views, assets/fonts, and basic test targets.
   - There is no evidence of a server, database, or networked backend; the app appears to be fully local.

2. **App entry point**
   - `freewrite/freewriteApp.swift` is the application bootstrap.
   - It wires the SwiftUI scene and is the top of the runtime graph for the app.
   - `freewrite.entitlements` indicates the app is sandboxed and likely uses macOS permissions relevant to recording or media access.

3. **Primary UI composition**
   - `freewrite/ContentView.swift` is the main screen/root view.
   - This is the likely coordinator for the app’s user flow, selecting between the writing experience and any media-related subviews.
   - For an architecture diagram, treat `ContentView` as the central UI boundary that hosts the app’s feature modules.

4. **Recording subsystem**
   - `freewrite/VideoRecordingView.swift` is a distinct feature boundary for capture/recording.
   - The name suggests it owns the user-facing recording experience and probably interfaces with macOS media APIs.
   - This is the most likely place where permissions, capture state, and recording controls are concentrated.

5. **Playback subsystem**
   - `freewrite/VideoPlayerView.swift` is the companion feature for reviewing recorded media.
   - It likely receives recorded output from the recording flow and presents playback UI.
   - In the diagram, keep playback separate from capture to show a clean producer/consumer boundary.

6. **Document/content defaults**
   - `freewrite/default.md` suggests the app ships with a default writing prompt, template, or starter content.
   - This is likely a local bundled resource rather than runtime-generated data.
   - It belongs in the “static content/resources” layer alongside assets and fonts.

7. **Resource layer**
   - `freewrite/Assets.xcassets` contains app icons and color assets used by the UI.
   - `freewrite/fonts/` includes a bundled font license and font assets used to shape the writing experience.
   - These are presentation resources, not business logic, but they materially affect the app’s look and feel.

8. **No backend / offline-first boundary**
   - The repository does not show any API clients, sync logic, persistence stack, or cloud integration.
   - That implies the architecture is likely offline-first and self-contained, with state managed locally in SwiftUI and system frameworks.
   - For a diagram, avoid adding external services unless you later find them in implementation files.

9. **Tests**
   - `freewriteTests/` holds unit tests and `freewriteUITests/` holds UI/integration tests.
   - These are separate validation layers around the app target, but they do not appear to introduce new runtime subsystems.
   - They’re useful to show as adjacent quality gates rather than part of the product path.

10. **Developer workflow / packaging**
   - The root `README.md` describes a very simple workflow: clone, open in Xcode, build.
   - That reinforces that the repo is a single Xcode project without additional build tooling or deployment orchestration.
   - The architecture is therefore centered on the Xcode app target and SwiftUI views.

11. **Likely data flow to diagram**
   - User launches app → `freewriteApp` creates the SwiftUI scene → `ContentView` coordinates the experience → `VideoRecordingView` captures a session → `VideoPlayerView` reviews output.
   - Static resources such as `default.md`, assets, and fonts feed the UI layer.
   - Any captured media/state is expected to stay on-device and be managed by the app and system frameworks.

12. **Diagram boundaries to preserve**
   - Separate **application bootstrap**, **main UI coordinator**, **recording**, **playback**, and **static resources**.
   - Keep **tests** and **preview assets** outside the runtime path.
   - Do not draw network, persistence, or backend boxes unless you confirm them in the source files.

Main entry points: [`freewrite/ContentView.swift`](https://github.com/farzaa/freewrite/blob/main/freewrite/ContentView.swift) (Main screen), [`freewrite/freewriteApp.swift`](https://github.com/farzaa/freewrite/blob/main/freewrite/freewriteApp.swift) (App entry), [`freewrite/VideoRecordingView.swift`](https://github.com/farzaa/freewrite/blob/main/freewrite/VideoRecordingView.swift) (Recording), [`freewrite/VideoPlayerView.swift`](https://github.com/farzaa/freewrite/blob/main/freewrite/VideoPlayerView.swift) (Playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App Runtime"]
  node_freewrite_app["App entry<br/>SwiftUI bootstrap<br/>[freewriteApp.swift]"]
  node_content_view["Main screen<br/>UI coordinator<br/>[ContentView.swift]"]
  node_recording_view["Recording<br/>capture feature"]
  node_player_view["Playback<br/>review feature"]
  node_entitlements["Entitlements<br/>sandbox config"]
end

subgraph group_resources["Resources"]
  node_default_md["Default content<br/>bundled markdown<br/>[default.md]"]
  node_assets[("App assets<br/>asset catalog<br/>[Assets.xcassets]")]
  node_fonts[("Fonts<br/>typography resources")]
  node_preview_assets[("Preview assets<br/>Xcode previews")]
end

subgraph group_quality["Quality Gates"]
  node_unit_tests["Unit tests<br/>test target"]
  node_ui_tests["UI tests<br/>test target"]
  node_ui_launch_tests["Launch tests<br/>ui test"]
end

node_project["Xcode project<br/>build project"]
node_readme["README<br/>usage docs<br/>[README.md]"]

node_project -->|"builds"| node_freewrite_app
node_freewrite_app -->|"hosts"| node_content_view
node_content_view -->|"routes to"| node_recording_view
node_content_view -->|"routes to"| node_player_view
node_freewrite_app -.->|"uses"| node_entitlements
node_recording_view -.->|"needs"| node_entitlements
node_content_view -->|"loads"| node_default_md
node_content_view -->|"styles with"| node_assets
node_content_view -->|"typesets with"| node_fonts
node_recording_view -->|"styles with"| node_assets
node_player_view -->|"styles with"| node_assets
node_recording_view -->|"produces"| node_player_view
node_preview_assets -.->|"supports"| node_content_view
node_unit_tests -->|"verifies"| node_freewrite_app
node_ui_tests -->|"verifies"| node_freewrite_app
node_ui_launch_tests -->|"verifies"| node_freewrite_app
node_readme -.->|"documents"| node_project

click node_freewrite_app "https://github.com/farzaa/freewrite/blob/main/freewrite/freewriteApp.swift"
click node_content_view "https://github.com/farzaa/freewrite/blob/main/freewrite/ContentView.swift"
click node_recording_view "https://github.com/farzaa/freewrite/blob/main/freewrite/VideoRecordingView.swift"
click node_player_view "https://github.com/farzaa/freewrite/blob/main/freewrite/VideoPlayerView.swift"
click node_entitlements "https://github.com/farzaa/freewrite/blob/main/freewrite/freewrite.entitlements"
click node_default_md "https://github.com/farzaa/freewrite/blob/main/freewrite/default.md"
click node_assets "https://github.com/farzaa/freewrite/blob/main/freewrite/Assets.xcassets"
click node_fonts "https://github.com/farzaa/freewrite/tree/main/freewrite/fonts"
click node_preview_assets "https://github.com/farzaa/freewrite/blob/main/freewrite/Preview Content/Preview Assets.xcassets"
click node_project "https://github.com/farzaa/freewrite/blob/main/freewrite.xcodeproj"
click node_unit_tests "https://github.com/farzaa/freewrite/blob/main/freewriteTests/freewriteTests.swift"
click node_ui_tests "https://github.com/farzaa/freewrite/blob/main/freewriteUITests/freewriteUITests.swift"
click node_ui_launch_tests "https://github.com/farzaa/freewrite/blob/main/freewriteUITests/freewriteUITestsLaunchTests.swift"
click node_readme "https://github.com/farzaa/freewrite/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_freewrite_app,node_content_view,node_recording_view,node_player_view,node_entitlements toneBlue
class node_default_md,node_assets,node_fonts,node_preview_assets toneAmber
class node_unit_tests,node_ui_tests,node_ui_launch_tests toneMint
class node_project,node_readme toneNeutral
```

## Components

### App Runtime

SwiftUI app entry and main feature flow

- [App entry](https://github.com/farzaa/freewrite/blob/main/freewrite/freewriteApp.swift): SwiftUI bootstrap · Application entry point and scene setup for the macOS app · `freewrite/freewriteApp.swift`
- [Main screen](https://github.com/farzaa/freewrite/blob/main/freewrite/ContentView.swift): UI coordinator · Root SwiftUI view that organizes the main user experience · `freewrite/ContentView.swift`
- [Recording](https://github.com/farzaa/freewrite/blob/main/freewrite/VideoRecordingView.swift): capture feature · User-facing video recording flow and capture controls · `freewrite/VideoRecordingView.swift`
- [Playback](https://github.com/farzaa/freewrite/blob/main/freewrite/VideoPlayerView.swift): review feature · Companion view for reviewing recorded media · `freewrite/VideoPlayerView.swift`
- [Entitlements](https://github.com/farzaa/freewrite/blob/main/freewrite/freewrite.entitlements): sandbox config · App sandbox and permissions boundary for macOS capabilities · `freewrite/freewrite.entitlements`

### Resources

Bundled content and presentation assets

- [Default content](https://github.com/farzaa/freewrite/blob/main/freewrite/default.md): bundled markdown · Starter document or prompt shipped with the app · `freewrite/default.md`
- [App assets](https://github.com/farzaa/freewrite/blob/main/freewrite/Assets.xcassets): asset catalog · Icons and color assets used by the UI · `freewrite/Assets.xcassets`
- [Fonts](https://github.com/farzaa/freewrite/tree/main/freewrite/fonts): typography resources · Bundled font files and licensing for the writing experience · `freewrite/fonts`
- [Preview assets](https://github.com/farzaa/freewrite/blob/HEAD/freewrite/Preview%20Content/Preview%20Assets.xcassets): Xcode previews · Static assets for SwiftUI previews · `freewrite/Preview Content/Preview Assets.xcassets`

### Quality Gates

Test targets around the app

- [Unit tests](https://github.com/farzaa/freewrite/blob/main/freewriteTests/freewriteTests.swift): test target · Unit-level validation for core app behavior · `freewriteTests/freewriteTests.swift`
- [UI tests](https://github.com/farzaa/freewrite/blob/main/freewriteUITests/freewriteUITests.swift): test target · UI and launch verification for the app flow · `freewriteUITests/freewriteUITests.swift`
- [Launch tests](https://github.com/farzaa/freewrite/blob/main/freewriteUITests/freewriteUITestsLaunchTests.swift): ui test · Startup-focused UI test coverage · `freewriteUITests/freewriteUITestsLaunchTests.swift`

### Other components

- [Xcode project](https://github.com/farzaa/freewrite/blob/main/freewrite.xcodeproj): build project · Project and workspace configuration for the app target · `freewrite.xcodeproj`
- [README](https://github.com/farzaa/freewrite/blob/main/README.md): usage docs · Simple local development and open-in-Xcode workflow · `README.md`

## Connections

- Xcode project → App entry: builds · Xcode project compiles and runs the app target
- App entry → Main screen: hosts · App bootstrap creates the SwiftUI scene containing the root view
- Main screen → Recording: routes to · Main screen presents the recording experience
- Main screen → Playback: routes to · Main screen presents the playback experience
- App entry → Entitlements: uses · App runtime is constrained by sandbox and permissions
- Recording → Entitlements: needs · Capture flow depends on media-related permissions
- Main screen → Default content: loads · Root experience may seed the writing flow with bundled text
- Main screen → App assets: styles with · Main UI uses catalog assets for appearance
- Main screen → Fonts: typesets with · Writing interface uses bundled fonts
- Recording → App assets: styles with · Recording UI uses shared visual assets
- Playback → App assets: styles with · Playback UI uses shared visual assets
- Recording → Playback: produces · Recorded media flows into playback/review
- Preview assets → Main screen: supports · Preview-only resources support SwiftUI previews
- Unit tests → App entry: verifies · Unit tests exercise app logic and view behavior
- UI tests → App entry: verifies · UI tests validate end-to-end app interactions
- Launch tests → App entry: verifies · Launch tests validate startup behavior
- README → Xcode project: documents · README describes the basic Xcode workflow