seedPass/docs/ARCHITECTURE.md

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. The Advanced CLI guide details all commands.
• FastAPI server – defined in seedpass.api. See the API Reference for endpoints.
• BeeWare GUI – located in seedpass_gui and explained in the GUI Adapter 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

Overview Diagram

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.