# How the Securo Frontend Is Structured: A Complete Architecture Guide

> Discover the Securo frontend architecture. Learn how Vite React TypeScript organizes UI components, domain logic, and routing for a clean, efficient codebase.

- Repository: [securo-finance/securo](https://github.com/securo-finance/securo)
- Tags: architecture
- Published: 2026-08-28

---

**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`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/global-chat-panel.tsx) – Collapsible conversation UI
- [`icon-picker.tsx`](https://github.com/securo-finance/securo/blob/main/icon-picker.tsx) – Custom icon selection widget
- [`member-form.tsx`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/api.ts) | Typed fetch wrappers, request/response transforms |
| [`api-errors.ts`](https://github.com/securo-finance/securo/blob/main/api-errors.ts) | Error classification and HTTP status mapping |
| [`invalidate-queries.ts`](https://github.com/securo-finance/securo/blob/main/invalidate-queries.ts) | TanStack Query cache invalidation helpers |

The [`api.ts`](https://github.com/securo-finance/securo/blob/main/api.ts) module exports functions like `fetchAccounts()` that components consume through `useQuery()` hooks.

### Authentication Utilities

- [`auth-config-utils.ts`](https://github.com/securo-finance/securo/blob/main/auth-config-utils.ts) – WebAuthn registration and assertion flows
- [`auth-errors.ts`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/transaction-status.ts) | Pure functions determining transaction states |
| [`rule-match-utils.ts`](https://github.com/securo-finance/securo/blob/main/rule-match-utils.ts) | Algorithm for matching transactions to user rules |
| [`rule-form-utils.ts`](https://github.com/securo-finance/securo/blob/main/rule-form-utils.ts) | Builders for rule creation/editing |
| [`format.ts`](https://github.com/securo-finance/securo/blob/main/format.ts) | Currency and number formatting |
| [`date-utils.ts`](https://github.com/securo-finance/securo/blob/main/date-utils.ts) | `date-fns` wrappers for consistent date handling |
| [`relative-time.ts`](https://github.com/securo-finance/securo/blob/main/relative-time.ts) | Human-readable time differences |

### Utilities

- [`i18n.ts`](https://github.com/securo-finance/securo/blob/main/i18n.ts) – Lightweight translation helper
- [`nav-items.ts`](https://github.com/securo-finance/securo/blob/main/nav-items.ts) – Navigation configuration data
- [`constants.ts`](https://github.com/securo-finance/securo/blob/main/constants.ts) – Application-wide enums and magic values

## Data Flow Pattern

The Securo frontend follows a **unidirectional data flow** pattern:

```typescript
// 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`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/vite.config.ts) | Dev server, build optimization, path aliases |
| [`vitest.config.ts`](https://github.com/securo-finance/securo/blob/main/vitest.config.ts) | Test environment, coverage, setup files |
| [`tsconfig.json`](https://github.com/securo-finance/securo/blob/main/tsconfig.json) | Strict TypeScript rules, path mapping (`@/*` → `src/*`) |
| [`tailwind.config.ts`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/frontend/src/App.tsx) – router and provider setup
- **API client**: [`frontend/src/lib/api.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/api.ts) – all backend communication
- **Auth logic**: [`frontend/src/lib/auth-config-utils.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/auth-config-utils.ts) – WebAuthn and session management
- **Transaction engine**: [`frontend/src/lib/transaction-status.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/transaction-status.ts) – state calculation
- **Rule matching**: [`frontend/src/lib/rule-match-utils.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/rule-match-utils.ts) – core matching algorithm
- **Formatting**: [`frontend/src/lib/format.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/format.ts) – currency and number display
- **Navigation**: [`frontend/src/lib/nav-items.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/nav-items.ts) – route definitions
- **Cache management**: [`frontend/src/lib/invalidate-queries.ts`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/auth-config-utils.ts) file manages WebAuthn flows and token refresh, while [`api.ts`](https://github.com/securo-finance/securo/blob/main/api.ts) attaches authentication headers to every request. The [`auth-errors.ts`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/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`](https://github.com/securo-finance/securo/blob/main/frontend/src/App.tsx) using React Router's `BrowserRouter`. Navigation item definitions are centralized in [`frontend/src/lib/nav-items.ts`](https://github.com/securo-finance/securo/blob/main/frontend/src/lib/nav-items.ts), keeping route configuration separate from component implementation.