How the Securo Frontend Is Structured: A Complete Architecture Guide

The Securo frontend is a Vite-powered React TypeScript application with a clean separation between UI components in src/components, domain logic in src/lib, and routing/configuration at the root level.

The securo-finance/securo repository implements a modern financial dashboard frontend that prioritizes maintainability, type safety, and testability. This guide breaks down exactly how files are organized, where business logic lives, and how data flows through the application according to the actual source code implementation.

Root Directory Layout

The frontend/ folder contains a standard Vite project structure:

frontend/
├── src/
│   ├── App.tsx              # Application entry point

│   ├── main.tsx             # React DOM mount

│   ├── index.css            # Global styles (Tailwind)

│   ├── vite-env.d.ts        # Vite type declarations

│   ├── components/          # UI building blocks

│   ├── lib/                 # Domain logic & utilities

│   ├── pages/               # Route-level components

│   └── hooks/               # Custom React hooks

├── public/                  # Static assets

├── index.html               # Vite entry HTML

├── vite.config.ts           # Build configuration

├── vitest.config.ts         # Test configuration

└── package.json             # Dependencies

According to the source code in package.json, the stack includes React 18, TypeScript, TanStack Query for data fetching, React Router for navigation, Tailwind CSS for styling, and Vitest for testing.

The Entry Point: App.tsx

The root component at frontend/src/App.tsx establishes the application's foundation by wiring together three critical systems:

1. QueryClientProvider – Wraps the tree with TanStack Query's caching layer
2. BrowserRouter – Enables client-side routing
3. Global layout – Renders navigation and responsive UI chrome

This file imports from src/lib/auth-config-utils.ts to initialize authentication state before any routes render.

Component Architecture (src/components/)

The components/ directory contains feature-specific, reusable UI pieces. Rather than a flat structure, components are organized by domain:

Subdirectory	Purpose
dialogs/	Modal overlays (confirmations, forms)
forms/	Input wrappers and validation UI
panels/	Sidebar and main content regions
chat/	Real-time messaging interface

Key files include:

• global-chat-panel.tsx – Collapsible conversation UI
• icon-picker.tsx – Custom icon selection widget
• member-form.tsx – User management input group

Components are designed as stateless, prop-driven units. They receive data via TanStack Query hooks imported from src/lib/api.ts rather than managing local state.

Domain Logic Layer (src/lib/)

The src/lib/ directory is where the Securo frontend keeps its brain. This is not a dumping ground—files are grouped by functional domain with clear naming conventions.

API and Data Layer

File	Responsibility
api.ts	Typed fetch wrappers, request/response transforms
api-errors.ts	Error classification and HTTP status mapping
invalidate-queries.ts	TanStack Query cache invalidation helpers

The api.ts module exports functions like fetchAccounts() that components consume through useQuery() hooks.

Authentication Utilities

• auth-config-utils.ts – WebAuthn registration and assertion flows
• auth-errors.ts – Authentication failure handling and retry logic

These files manage token refresh, session persistence, and the WebAuthn ceremony integration.

Financial Domain Logic

File	Function
transaction-status.ts	Pure functions determining transaction states
rule-match-utils.ts	Algorithm for matching transactions to user rules
rule-form-utils.ts	Builders for rule creation/editing
format.ts	Currency and number formatting
date-utils.ts	date-fns wrappers for consistent date handling
relative-time.ts	Human-readable time differences

Utilities

• i18n.ts – Lightweight translation helper
• nav-items.ts – Navigation configuration data
• constants.ts – Application-wide enums and magic values

Data Flow Pattern

The Securo frontend follows a unidirectional data flow pattern:

// 1. Domain function in src/lib/api.ts
export async function fetchAccounts(): Promise<Account[]> {
  const res = await fetch('/api/accounts', {
    headers: getAuthHeaders(), // from auth-config-utils.ts
  });
  if (!res.ok) throw await parseApiError(res); // from api-errors.ts
  return res.json();
}

// 2. Component consumes via TanStack Query
// src/components/account-list.tsx
import { useQuery } from '@tanstack/react-query';
import { fetchAccounts } from '../lib/api';
import { formatCurrency } from '../lib/format';

export function AccountList() {
  const { data: accounts, isLoading } = useQuery(['accounts'], fetchAccounts);
  
  if (isLoading) return <Spinner />;
  
  return (
    <ul>
      {accounts.map(acct => (
        <li key={acct.id}>
          {acct.name}: {formatCurrency(acct.balance, acct.currency)}
        </li>
      ))}
    </ul>
  );
}

Testing Strategy

Tests live co-located with implementation files:

src/lib/
├── transaction-status.ts
├── transaction-status.test.ts  # Unit tests for pure logic

└── ...

The vitest.config.ts enables this pattern with the include: ['src/**/*.test.ts'] glob. Pure utility functions in src/lib/ have the highest test coverage since they contain the most complex business logic.

Build and Tooling Configuration

Config File	Purpose
vite.config.ts	Dev server, build optimization, path aliases
vitest.config.ts	Test environment, coverage, setup files
tsconfig.json	Strict TypeScript rules, path mapping (@/* → src/*)
tailwind.config.ts	Design token customization
eslint.config.mjs	Lint rules with TypeScript and React hooks plugins

The Vite configuration uses @vitejs/plugin-react-swc for fast compilation and sets up proxy rules for local API development.

File Reference Guide

When navigating the Securo frontend codebase, these are the authoritative source locations:

• Entry point: frontend/src/App.tsx – router and provider setup
• API client: frontend/src/lib/api.ts – all backend communication
• Auth logic: frontend/src/lib/auth-config-utils.ts – WebAuthn and session management
• Transaction engine: frontend/src/lib/transaction-status.ts – state calculation
• Rule matching: frontend/src/lib/rule-match-utils.ts – core matching algorithm
• Formatting: frontend/src/lib/format.ts – currency and number display
• Navigation: frontend/src/lib/nav-items.ts – route definitions
• Cache management: frontend/src/lib/invalidate-queries.ts – query invalidation

Summary

• The Securo frontend uses Vite + React + TypeScript with TanStack Query for data and React Router for navigation
• src/components/ contains UI components grouped by feature domain, kept stateless and reusable
• src/lib/ is the critical domain layer: API clients, auth utilities, financial logic, and formatting helpers
• Pure business logic (transaction status, rule matching) lives in src/lib/ with co-located unit tests
• App.tsx is the single entry point that wires providers, routing, and global layout together
• Path aliases (@/*) and strict TypeScript configuration enforce clean imports throughout

Frequently Asked Questions

Where does the Securo frontend handle API authentication?

The frontend/src/lib/auth-config-utils.ts file manages WebAuthn flows and token refresh, while api.ts attaches authentication headers to every request. The auth-errors.ts module handles authentication failures and retry logic.

How does the Securo frontend organize its React components?

Components live in frontend/src/components/ with subdirectory groupings by feature (dialogs, forms, panels, chat). They follow a stateless design pattern, receiving data through TanStack Query hooks rather than managing local state.

What testing framework does the Securo frontend use?

The frontend uses Vitest with React Testing Library, configured in vitest.config.ts. Tests are co-located with source files using the *.test.ts naming convention, with highest coverage on pure utility functions in src/lib/.

How is routing configured in the Securo frontend?

Routing is initialized in frontend/src/App.tsx using React Router's BrowserRouter. Navigation item definitions are centralized in frontend/src/lib/nav-items.ts, keeping route configuration separate from component implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}