> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowxi.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

This documentation describes the **Flowxi backend platform** from a **purely technical and architectural standpoint**.

Flowxi is a **private, internal backend** built to power Flowxi-owned products and services.
It is **not a public API platform** and is not intended for third-party integrations without explicit authorization.

The goal of this documentation is to explain **how the platform behaves**, **why certain decisions were made**, and **how frontend applications must interact with it safely and correctly**.

***

## What Flowxi is (and is not)

### What Flowxi **is**

Flowxi is:

* A **stateful backend platform** for fintech products
* A **security-first API system**
* A **single source of truth** for users, sessions, and financial state
* A **localization-aware** system by default
* A backend designed for **deterministic behavior** and auditability

### What Flowxi **is not**

Flowxi is **not**:

* A generic SaaS API
* A public developer platform
* A loosely consistent microservice mesh
* A frontend-driven backend (BFF-only logic is avoided)

***

## Platform responsibilities

Flowxi is responsible for all **critical backend concerns**, including:

### Identity & access

* User lifecycle management
* Authentication and authorization
* Session and device management
* Two-factor authentication (TOTP)
* Anti-enumeration and rate limiting

### Financial core

* Wallet ownership and balances
* Transaction recording
* Internal ledger consistency
* Idempotent financial operations

### Compliance & state management

* KYC and verification workflows
* Regulatory state transitions
* Blocking, suspension, and account closure logic
* Explicit, traceable user states

### Communication & localization

* Transactional emails
* Security notifications
* Fully localized API responses
* Deterministic fallback behavior

Anything **UI-related**, **presentation-specific**, or **business-orchestration-heavy** is intentionally left to frontend or product layers.

***

## Core design principles

Flowxi follows a small number of **non-negotiable principles**.

### 1. Security first (always)

Security is not an afterthought:

* All sensitive endpoints are authenticated
* Public endpoints are rate-limited
* Authentication flows are anti-enumeration by design
* 2FA secrets are never exposed after enrollment
* Tokens are scoped per device
* Critical actions are auditable

No endpoint assumes “good behavior” from the client.

***

### 2. API-first, not UI-first

Every capability exists as an API:

* Frontends consume the same APIs as internal tools
* No hidden server-side flows
* No session magic or implicit state
* All behavior is explicit and documented

If something exists, it has an endpoint.

***

### 3. State-driven logic

Flowxi avoids implicit behavior.

Users, wallets, and processes rely on **explicit states**, such as:

* `pending`
* `active`
* `blocked`
* `closed`

State transitions are:

* Controlled
* Validated
* Logged
* Predictable

There are no “soft” or inferred states.

***

### 4. Deterministic behavior

Given the same input:

* The API returns the same structure
* The same error code
* The same HTTP status

No endpoint relies on timing assumptions or client-side guesses.

Frontend logic must always rely on:

* `code` fields (machine-readable)
* not `message` strings (human-readable)

***

### 5. Localization by default

Localization is **not optional** in Flowxi.

Every request resolves a locale using a strict order:

1. `X-App-Locale`
2. `Accept-Language`
3. `user.locale` (authenticated)
4. fallback (`fr`)

This locale applies to:

* API response messages
* Validation errors
* Authentication errors
* Emails sent during the request

There is **no mixed-language state**.

***

## High-level architecture

At a high level, Flowxi is structured around **clear responsibility layers**:

1. **Authentication & security**
   * Login, registration
   * Sessions and devices
   * 2FA and step-up verification

2. **User & identity**
   * User records
   * Status and lifecycle
   * Preferences and locale

3. **Financial core**
   * Wallets
   * Balances
   * Transactions and movements

4. **Compliance**
   * KYC workflows
   * Regulatory constraints
   * Blocking and escalation

5. **Communication & localization**
   * Emails
   * Notifications
   * Translations and fallback

Each layer is documented independently but designed to work as a coherent whole.

***

## How to read this documentation

This documentation is **not linear**.

Recommended reading order:

1. **Authentication overview**\
   Understand access rules, tokens, and sessions.
2. **Login & 2FA**\
   Learn how secure authentication actually works.
3. **Errors**\
   Learn how to handle failures correctly.
4. **Localization**\
   Understand how messages and emails are localized.
5. **API reference**\
   Use for exact request/response formats.

This documentation assumes:

* Familiarity with REST APIs
* Experience with frontend-backend integration
* Basic security awareness (tokens, headers, rate limits)

***

## Final note

Flowxi favors **clarity over convenience**.

If something feels strict, verbose, or explicit, it is intentional.
The platform is designed for **financial-grade correctness**, not shortcuts.

Every decision documented here exists to reduce ambiguity,
increase security, and ensure predictable behavior at scale.