FastAPI Backend Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• backend/app/main.py
• backend/app/routes/analytics.py
• README.md
• CLAUDE.md
• BANK_INTEGRATION_GUIDE.md
• deploy/compose/docker-compose.yml

The FastAPI backend serves as the core data pipeline for the Syllogic personal finance platform. Its primary purpose is to handle heavy data processing tasks, including transaction enrichment, AI-powered categorization, and complex financial analytics, while the Next.js frontend manages the user interface and basic CRUD operations.

This backend architecture is designed to be a "service-only" layer that interacts with a shared PostgreSQL database. It utilizes FastAPI for high-performance API routing and integrates with Celery and Redis to handle asynchronous background jobs such as scheduled bank synchronizations and batch data refreshes.

Sources: README.md:104-120, CLAUDE.md:14-30

Core API Infrastructure

The backend application is initialized in backend/app/main.py. It includes middleware for security, CORS configuration, and modular routing.

Authentication Middleware

The backend implements a specialized internal_auth_middleware. This middleware intercept requests to ensure they originate from the authorized frontend or authenticated internal services. It uses an INTERNAL_AUTH_SECRET to verify signed headers before allowing access to protected /api/ paths, excluding health checks.

The diagram above illustrates the request flow through the internal authentication layer.
Sources: backend/app/main.py:59-100, CLAUDE.md:108-112

Global Configuration

Feature	Environment Variable	Description
API Documentation	API_DOCS_ENABLED	Enables Swagger UI at /docs when set to true.
CORS Origins	CORS_ALLOW_ORIGINS	Comma-separated list of allowed frontend URLs.
DB Migrations	AUTO_CREATE_TABLES	If true, SQLAlchemy will create tables (Drizzle is preferred).
Internal Auth	INTERNAL_AUTH_SECRET	Shared secret for verifying internal signed requests.

Sources: backend/app/main.py:44-57, deploy/compose/docker-compose.yml:50-60

Analytics Endpoints

The analytics module, located in backend/app/routes/analytics.py, provides complex aggregations and data structures for financial visualizations like Sankey diagrams and monthly cashflow charts.

Cashflow and Balances

• GET /api/analytics/cashflow/monthly: Aggregates income and expenses by year and month. It filters transactions by user_id and ensuring include_in_analytics is true.
• GET /api/analytics/account-balances: Calculates historical balances. If a to_date is provided, it calculates the balance at that specific point in time by subtracting subsequent transactions from the current functional balance.

Sources: backend/app/routes/analytics.py:14-30, backend/app/routes/analytics.py:157-190

Sankey Diagram Data

The GET /api/analytics/sankey endpoint generates a node-link structure representing the flow of money from income sources through a central "Total Income" node into various expense categories and "Savings".

The flow represents how the backend structures data for the Sankey visualization.
Sources: backend/app/routes/analytics.py:70-154

Synchronization and Integrations

The backend handles bank integrations using an adapter pattern. This allows the system to support various data sources such as Plaid, TrueLayer, or manual CSV imports.

Integration Architecture

The system utilizes a SyncService that interacts with specific BankAdapter implementations to fetch accounts and transactions.

Endpoint	Method	Purpose
/api/sync/plaid/sync	POST	Triggers synchronization for a Plaid-connected account.
/api/sync/revolut/csv	POST	Processes a manual Revolut CSV upload.
/api/health	GET	Unprotected endpoint for service readiness checks.

Sources: BANK_INTEGRATION_GUIDE.md:7-15, BANK_INTEGRATION_GUIDE.md:105-115, backend/app/main.py:126-130

Background Task Processing

For long-running tasks like AI categorization or scheduled syncs, the backend relies on Celery workers.

Summary

The FastAPI Backend Endpoints constitute the high-performance data processing arm of Syllogic. By isolating complex analytics, AI categorization, and bank integrations into this Python-based service, the architecture maintains a clean separation of concerns. The use of signed internal authentication ensures secure communication with the Next.js frontend, while the integration of Celery and Redis allows for scalable, asynchronous financial data management.