Saltar a contenido

🎨 Frontend Development

This section covers the SvelteKit frontend architecture, components, and development patterns.

📖 Overview

LibreFolio's frontend is built with:

  • SvelteKit 2.x - Full-stack web framework
  • Svelte 5 - Reactive UI framework using Runes ($state, $derived, $effect)
  • Tailwind CSS 4.x - Utility-first CSS (configured via @theme in CSS)
  • TypeScript - Type safety
  • lucide-svelte - Icon library

📂 Directory Structure

frontend/
├── src/
│   ├── routes/           # SvelteKit pages and routing
│   │   ├── (app)/        # Authenticated app routes (Dashboard, Brokers, etc.)
│   │   │   ├── dashboard/
│   │   │   ├── brokers/
│   │   │   │   └── [id]/    # Broker detail page
│   │   │   ├── assets/
│   │   │   ├── transactions/
│   │   │   ├── fx/
│   │   │   ├── files/
│   │   │   └── settings/
│   │   └── +page.svelte  # Login page (Public)
│   └── lib/
│       ├── api/          # API client (Zodios, generated from OpenAPI)
│       ├── components/   # Reusable components
│       │   ├── auth/     # LoginCard, RegisterCard, ForgotPasswordCard
│       │   ├── brokers/  # Broker cards, forms, icon, import
│       │   ├── files/    # FilesTable with DataTable
│       │   ├── layout/   # Sidebar, Header, LanguageSelector
│       │   ├── settings/ # Settings tabs (Profile, Preferences, Global, About)
│       │   ├── table/    # DataTable suite (DataTable, toolbar, pagination, column filter, SelectionBar)
│       │   └── ui/       # Generic UI atoms
│       │       ├── input/    # PasswordInput, PasswordStrength
│       │       ├── media/    # ImageCropper, ImageEditModal, AssetPickerModal, FileEditModal
│       │       ├── modals/   # ModalBase, ConfirmModal
│       │       ├── select/   # SimpleSelect, SearchSelect + specialized selects
│       │       ├── tabs/     # TabBar (used standalone and by PageToolbar)
│       │       └── toolbar/  # PageToolbar — shared responsive shell (see Toolbar & Responsive Layout)
│       ├── i18n/         # Internationalization (EN, IT, FR, ES)
│       ├── stores/       # Store Client System (State Management)
│       │   ├── app/          # auth, clientSession, settings, globalSettings, themeStore, language, privacyStore, toastStore, …
│       │   ├── core/         # EntityStore, EditBuffer, TimeSeriesStore
│       │   ├── reference/    # brokerStore, assetStore, currencyStore, countryStore, sectorStore, fxRoutesStore
│       │   ├── portfolio/    # portfolioStore (report cache), portfolioMutation, lotsAnalysisStore, dashboardViewStore
│       │   ├── risk/         # riskStore, riskBenchmarkStore, riskPanelController
│       │   ├── transactions/ # txStore, transactionTypeStore
│       │   ├── fx/           # fxCardInversionStore
│       │   ├── files/        # imagePreviewCache
│       │   ├── assetPriceStoreRegistry.ts     # Registry: price series per asset and currency
│       │   ├── fxStoreRegistry.ts             # Registry: rate series per FX pair
│       │   ├── dateRangeStore.svelte.ts       # Date range shared by the pages
│       │   ├── dateRangeController.svelte.ts  # Per-page wiring of that date range
│       │   ├── chartSettingsStore.svelte.ts   # Chart aesthetics and signal configs (localStorage)
│       │   ├── currencyGraphStore.ts          # FX currency graph (session cache)
│       │   └── signalCatalogStore.svelte.ts   # Signal catalog per domain (asset, FX)
│       ├── types/        # TypeScript type definitions
│       └── utils/        # Utilities (urlFilters, chartUtils, …)
│           ├── files/        # imageCrop.ts, upload.ts
│           └── layout/       # responsiveLayout.svelte.ts, labelShrink.ts, dropdownPosition.ts
├── e2e/                  # Playwright E2E tests
└── static/               # Static assets

⚡ Svelte 5 Runes

New components use Svelte 5's Runes for reactivity, but a minority of older components use no rune at all, so Svelte compiles them in legacy mode (export let props, $: statements). The one consequence to know: in a legacy component, a function call inside a template expression compiles into $.untrack(…), so runes state read inside that function is not tracked — that is why the Brokers page stopped following the privacy toggle (R20). Render such a value through a runes child (e.g. lib/components/ui/display/CurrencyAmount.svelte) or migrate the component; see Legacy components freeze masked output.

🔑 Key Runes Used

  • $state: Declares reactive state. 
    let count = $state(0);
  • $derived: Declares derived state (automatically updates when dependencies change). 
    let double = $derived(count * 2);
  • $effect: Side effects (runs when dependencies change). 
    $effect(() => {
    console.log(count);
});
  • $props: Declares component props. 
    let { title, active = false } = $props();

📚 Documentation Sections

🏗️ Build & Development

Frontend tasks are managed via dev.py front:

# Start Vite dev server with Hot Module Replacement
./dev.py front dev

# Build for production (output in frontend/build/)
./dev.py front build

# Build with source maps for debugging
./dev.py front build --debug

# Type-check with svelte-check
./dev.py front check

# Preview production build locally
./dev.py front preview
Command Description
front dev Starts Vite at localhost:5173, proxies API calls to backend
front build Production build with minification and tree-shaking
front build --debug Build with source maps (useful for debugging deployed code)
front check Runs svelte-check for TypeScript and Svelte diagnostics
front preview Serves the production build locally for testing

Development workflow

Run ./dev.py server in one terminal and ./dev.py front dev in another. The Vite dev server proxies /api calls to the backend automatically.

Topic Description
DataTable Advanced table with sorting, filtering, pagination
Toolbar & Responsive Layout PageToolbar shell, threshold-driven tiers, per-page tuning
FX Chain Algorithm DFS + graphology for multi-step FX routes
Authentication LoginCard, RegisterCard, ForgotPasswordCard
Settings User preferences, profile, and global settings
File Upload File uploader, image crop, asset picker