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. Use seedpass --help and seedpass <command-group> --help for command-level docs.
• FastAPI server – defined in seedpass.api.
• BeeWare GUI – located in seedpass_gui. Packaging and install notes are in packaging.md.

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 are available through the CLI (seedpass vault --help) and implemented in seedpass.cli.vault.

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.