From 47ea11b533257390b7454496438e7541ceb1cb6a Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Thu, 17 Jul 2025 21:50:18 -0400
Subject: [PATCH] docs: describe architecture

---
 README.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/README.md b/README.md
index 7b39a4d..1c66e3d 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,7 @@ SeedPass now uses the `portalocker` library for cross-platform file locking. No
 ## Table of Contents
 
 - [Features](#features)
+- [Architecture Overview](#architecture-overview)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
   - [1. Clone the Repository](#1-clone-the-repository)
@@ -65,9 +66,39 @@ SeedPass now uses the `portalocker` library for cross-platform file locking. No
 - **Relay Management:** List, add, remove or reset configured Nostr relays.
 - **Offline Mode:** Disable all Nostr communication for local-only operation.
 
+
 A small on-screen notification area now shows queued messages for 10 seconds
 before fading.
 
+## Architecture Overview
+
+SeedPass follows a layered design. The **`seedpass.core`** package exposes the
+`PasswordManager` along with service classes (e.g. `VaultService` and
+`EntryService`) that implement the main API used across interfaces.
+The command line tool in **`seedpass.cli`** is a thin adapter built with Typer
+that delegates operations to this API layer.
+
+The BeeWare desktop interface lives in **`seedpass_gui.app`** and can be
+started with either `seedpass-gui` or `python -m seedpass_gui`. It reuses the
+same service objects to unlock the vault, list entries and search through them.
+
+An optional browser extension can communicate with the FastAPI server exposed by
+`seedpass.api` to manage entries from within the browser.
+
+```mermaid
+graph TD
+    core["seedpass.core"]
+    cli["CLI"]
+    api["FastAPI server"]
+    gui["BeeWare GUI"]
+    ext["Browser Extension"]
+
+    cli --> core
+    gui --> core
+    api --> core
+    ext --> api
+```
+
 ## 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.