From 474f2d134b95b045794c4908a189e9c79bb1c05c Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Thu, 17 Jul 2025 22:25:34 -0400
Subject: [PATCH] Add architecture documentation

---
 README.md            |  2 ++
 docs/ARCHITECTURE.md | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 docs/ARCHITECTURE.md

diff --git a/README.md b/README.md
index 1c66e3d..2cbf771 100644
--- a/README.md
+++ b/README.md
@@ -99,6 +99,8 @@ graph TD
     ext --> api
 ```
 
+See `docs/ARCHITECTURE.md` for details.
+
 ## Prerequisites
 
 - **Python 3.8+** (3.11 or 3.12 recommended): Install Python from [python.org](https://www.python.org/downloads/) and be sure to check **"Add Python to PATH"** during setup. Using Python 3.13 is currently discouraged because some dependencies do not ship wheels for it yet, which can cause build failures on Windows unless you install the Visual C++ Build Tools.  
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..f8416b8
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,41 @@
+# SeedPass Architecture
+
+SeedPass follows a layered design that keeps the security-critical logic isolated in a reusable core package. Interfaces like the command line tool, REST API and graphical client act as thin adapters around this core.
+
+## Core Components
+
+- **`seedpass.core`** – houses all encryption, key derivation and vault management code.
+- **`VaultService`** and **`EntryService`** – thread-safe wrappers exposing the main API.
+- **`PasswordManager`** – orchestrates vault operations, migrations and Nostr sync.
+
+## Adapters
+
+- **CLI/TUI** – implemented in [`seedpass.cli`](src/seedpass/cli.py). The [Advanced CLI](docs/docs/content/01-getting-started/01-advanced_cli.md) guide details all commands.
+- **FastAPI server** – defined in [`seedpass.api`](src/seedpass/api.py). See the [API Reference](docs/docs/content/01-getting-started/02-api_reference.md) for endpoints.
+- **BeeWare GUI** – located in [`seedpass_gui`](src/seedpass_gui/app.py) and explained in the [GUI Adapter](docs/docs/content/01-getting-started/06-gui_adapter.md) page.
+
+## Planned Extensions
+
+SeedPass is built to support additional adapters. Planned or experimental options include:
+
+- A browser extension communicating with the API
+- Automation scripts using the CLI
+- Additional vault import/export helpers described in [JSON Entries](docs/docs/content/01-getting-started/03-json_entries.md)
+
+## Overview Diagram
+
+```mermaid
+graph TD
+    core["seedpass.core"]
+    cli["CLI / TUI"]
+    api["FastAPI server"]
+    gui["BeeWare GUI"]
+    ext["Browser extension"]
+
+    cli --> core
+    api --> core
+    gui --> core
+    ext --> api
+```
+
+All adapters depend on the same core, allowing features to evolve without duplicating logic across interfaces.