👨‍💻 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:

• 📦 Installation (Development) — Clone, install dependencies, start the server
• 🔄 Development Workflow — All dev.py commands at a glance

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
  • 🗄️ Database Migrations — Alembic workflow, SQLite batch mode
  • ⚙️ Configuration — .env, Pydantic BaseSettings
• 🔐 Core Systems:
  • 🛡️ Security & Authentication — JWT cookies, endpoint protection
  • 👤 Users & Roles — Login flow, session, user roles
  • 🔑 Access Control (RBAC) — Broker sharing permissions
  • ⚙️ Settings System — Global + user settings, fallback logic
• 🗃️ 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
• 💱 Foreign Exchange (FX) — Multi-provider currency conversion system
  • 🔀 FX Configuration & Routing — Chain routing algorithm
  • 🏛️ FX Providers List — ECB, FED, BOE, SNB details
• 🗃️ 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

---

🌐 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