👨‍💻 Developer Manual

Welcome to the Developer Manual. This section contains in-depth technical documentation about the LibreFolio architecture, codebase, and development practices.

---

🚀 Getting Started

Set up your local development environment and learn the daily workflow:

• 📦 Host Installation — Set up Python, Node.js, and Pipenv environment
• 🔄 Developer Workflow — Start Vite dev server and view all development CLI commands
• 🚦 Lint Gates & Code Policy — The ruff gate list, justified-noqa conventions, and code policies the linter can't express

Quick start

./dev.py install         # Install all dependencies
./dev.py db create-clean # Create fresh database
./dev.py server          # Start backend server
./dev.py front dev       # Start frontend dev server (separate terminal)

---

🏗️ Architecture & Technologies

• 🗺️ System Overview — High-level system diagrams, tech stack, and design decisions
• 🧩 Technologies & Patterns:
  • ⚡ Async Architecture — async/await, aiosqlite, non-blocking I/O
  • 🔌 Registry & Plugin System — Provider plugins for BRIM, Assets, FX
  • 🧰 Tool Plugins — Atomic, typed calculations behind a versioned catalogue (first tool: the PAC allocator), each computed in a spawned process the executor owns
  • 🗄️ Database Migrations — Alembic workflow, SQLite batch mode
  • ⚙️ Configuration — .env loading, Pydantic BaseSettings, global settings (admin options: Configuration)
• 🔐 Core Systems:
  • 🛡️ Security & Authentication — JWT cookies, endpoint protection
  • 👤 Users & Roles — Login flow, session, user roles
  • 🔑 Access Control (RBAC) — Broker sharing permissions
  • ⚙️ Settings System — SETTINGS_REGISTRY, user vs global storage, base-currency resolution
  • 🧹 Cache Registry & Admin — named theine caches, /settings/cache/* admin endpoints
• 🗃️ Database Schema:
  • 📊 Overview — ER diagram, design philosophy
  • 👤 Users & Access · 🏦 Brokers & Transactions · 📈 Assets & Pricing · 💱 FX Rates & Routes

---

⚙️ Backend

• 📥 BRIM (Broker Report Import Manager) — CSV/Excel import pipeline, plugin architecture
• 📈 Asset Pricing & Metadata — How asset prices and metadata are fetched and managed
• 🧮 Financial Math Layer — The one home of financial calculations: package map, layer rules, guards
• 📏 Price Resolver — The single daily valuation-mark source behind NAV/MWRR/TWRR/ROI
• 💱 Foreign Exchange (FX) — Multi-provider currency conversion system
  • 🔀 FX Configuration & Routing — Chain routing algorithm
  • 🔌 FX Providers — ECB, FED, BOE, SNB technical details
• 📉 Risk Engine — Bulk risk analytics behind /api/v1/risk: plugin catalogue, eligibility verdicts, simulation and optimization in spawned worker pools
• 🗃️ Database Schema — SQLite schema split by subsystem (Users, Brokers, Assets, FX)

---

🎨 Frontend

• 🖥️ Frontend Development — SvelteKit architecture, Svelte 5 Runes, directory structure
  • 🧱 Components — Reusable UI component library
  • 📄 Pages — Application pages and routing
  • 📦 State Management — Stores and reactive state
  • 🎨 Styling — Tailwind CSS 4 and theming
• 🌍 Internationalization (i18n) — Multi-language support, audit CLI, key management
• 🔗 FX Chain Algorithm — DFS + graphology for multi-step FX routes
• 🧭 Onboarding Guides — Welcome setup, intro tour and contextual guides, with versioned per-user progress kept by the backend

---

🌐 API

• 📋 API Overview — OpenAPI-first workflow, schema export, TypeScript client generation
• 📖 API Reference — FastAPI endpoint documentation

---

🧪 Testing

• 🔍 Test Walkthrough — Full guide to the 10-category test suite
  • 🔧 Backend: External, Database, Services, Utils, Schemas, API, E2E
  • 🎭 Frontend (Playwright): Front-Utility, Front-User, Front-FX