commit 20896c851e80898c5eb044db25016b00d7d59380
parent 1d8e9374d38c55b89d735333b7ff8a0d9432ebab
Author: Michael Camilleri <[email protected]>
Date: Mon, 18 May 2026 08:31:21 +0900
Add high-level architecture description to AGENTS.md
Diffstat:
1 file changed, 12 insertions(+), 0 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -7,6 +7,18 @@
- Crossmate syncs shared game state using Apple's CloudKit.
- Scripts for common tasks, including running tests, live in `Scripts/`.
+## Code Structure
+
+- `Crossmate/` is the iOS/iPadOS app — the only thing the build/test scripts compile. It is layered:
+ - `Models/` — domain types: puzzle/grid representation, players, catalog, and the `.xd` format parser (`XD.swift`).
+ - `Persistence/` — local store only: Core Data (`CrossmateModel.xcdatamodeld`), plus `GameStore`/`GameMutator`.
+ - `Sync/` — the CloudKit layer, driven by **raw `CKSyncEngine`** (not NSPersistentCloudKitContainer or SwiftData): per-game zones and `CKShare` collaboration. `Moves`/`MovesUpdater`/`GridStateMerger` carry collaborative grid state; `Friend*`/`Share*` carry sharing; `RecordSerializer` maps records.
+ - `Services/` — app-level singletons and I/O: import, NYT fetch/auth, keychain, monitors, and the `*ToXDConverter` format converters. (Note: `CloudService` lives here but is *not* the sync engine — that is `Sync/SyncEngine.swift`.)
+ - `Views/` — SwiftUI.
+- `Shared/` — types shared with extensions.
+- Puzzles are plain-text `.xd` files; `.puz` and NYT puzzles are converted to XD on import. `Puzzles/Bundled/` ships as app resources; `Puzzles/Debug/` is dev-only fixtures.
+- `Crossmake/` is a **separate offline SPM package**, not part of the app and not built by the app scripts. It holds the CLI tools that author the bundled puzzles (`Crossmake` fills grids, `Wordmake` curates word lists).
+
## Working Notes
- The user will handle making commits.
