From 84631c7660974acd194458dd797f9d5955c3faa8 Mon Sep 17 00:00:00 2001
From: cyph3rasi <1+cyph3rasi@noreply.githop.xyz>
Date: Sat, 11 Jul 2026 19:41:08 +0000
Subject: [PATCH] Publish Architecture documentation

---
 Architecture.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 Architecture.md

diff --git a/Architecture.md b/Architecture.md
new file mode 100644
index 0000000..c871df0
--- /dev/null
+++ b/Architecture.md
@@ -0,0 +1,54 @@
+# Architecture
+
+Hop uses Git under the hood, but it is not merely a directory of metadata files
+inside `.git`.
+
+## Git responsibilities
+
+Git provides:
+
+- content-addressed blobs and trees;
+- synthetic commits for immutable snapshots;
+- detached worktrees for attempt isolation;
+- three-way merge behavior;
+- diffs and path inspection; and
+- interoperability with existing repositories.
+
+Hop never needs to move the user's active branch or rewrite the real index.
+Private objects are pinned beneath `refs/hop/states/*`; accepted history is
+mirrored at `refs/hop/accepted`.
+
+## Hop responsibilities
+
+`.hop/hop.db` is a SQLite WAL database containing:
+
+- prompt/task/attempt identity;
+- typed state edges and accepted lineage;
+- evidence tied to exact source trees;
+- session heads for Desktop follow-ups;
+- materialized-root state; and
+- immutable audit events.
+
+## Project layout
+
+```text
+.hop/
+├── hop.db
+├── workspaces/
+├── checks/
+├── integration/
+└── *.lock
+```
+
+`.hop/` is added to `.git/info/exclude`, not the public `.gitignore`. Hop refuses
+initialization when `.hop` is already tracked as user-owned project content.
+
+## Acceptance consistency
+
+Acceptance is serialized and compare-and-swapped. SQLite is authoritative;
+derived Git refs can be repaired by `hop doctor --repair`. Desktop landing also
+tracks which accepted state is physically visible, allowing safe catch-up with
+`hop sync` without treating a divergent folder as disposable.
+
+For the full product direction, read the
+[product blueprint](https://githop.xyz/GnosysLabs/Hop/src/branch/main/docs/product-blueprint.md).