Skip to content

(AI generated. Not reviewed.)

Fichero Developer Docs

This section explains how the current Fichero codebase works for contributors. It is grounded in the live SwiftUI client under fichero/fichero/, the FastAPI engine under fichero-server/src/fichero_server/, and the architecture notes already present in docs/contributor/architecture/.

Table of Contents

Read This First

Fichero is not a single-process desktop app. The default macOS path is a native SwiftUI app over a local fichero-server server (Python, FastAPI), while other Apple clients connect to an explicitly configured remote engine host.

The shortest accurate picture is:

SwiftUI app -> UDS (local) / pinned HTTPS -> FastAPI engine -> DuckDB + LanceDB
                                                     -> LangGraph workflows
                                                     -> LLM providers via LangChain integrations

That architecture shapes almost every contributor task:

  • UI work usually means changing SwiftUI views and hand-written service wrappers.
  • data, AI, ingest, and search work usually means changing FastAPI routes and backend modules.
  • contract changes require an OpenAPI sync so the Swift side compiles again.

Contributing

For environment setup, build commands, and branch discipline, see Setup and Contributing. The key mechanics: commit directly to the milestone branch, register new Swift files with scripts/add-swift-file.rb, use conventional commits with issue references, and never push to main without a PR.

For audited cross-surface mutations, the starting point is the action registry. The registry-backed routes are the shared path for surfaces such as chat tools, App Intents, and undoable action flows, but the backend still has direct db.save(...) routes outside that layer today. See Action Registry for the current architecture and Security Model for the shared-secret token, multi-user ACL, transport, and audit attribution.

Core Reference Material In This Repo