Introduction and Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Syllogic is a modern, full-stack personal finance management platform designed to track savings, expenses, investments, and subscriptions. It leverages a two-service architecture to provide automated bank synchronization, AI-powered transaction categorization, and interactive financial analytics.
The system is built to automate tedious financial tracking tasks while providing data-driven insights through a centralized dashboard. It supports multi-account management, CSV data imports, and scheduled background synchronization.
Sources: README.md:3-33, CLAUDE.md:5-10
System Architecture
The application employs a two-service architecture sharing a single PostgreSQL database. The frontend handles the user interface and CRUD operations, while the backend manages the data pipeline, enrichment, and background tasks.
Architecture Overview
- Frontend (Next.js): Responsible for the UI, authentication (via BetterAuth), and data mutations using Server Actions and Drizzle ORM.
- Backend (Python/FastAPI): Manages transaction enrichment, categorization, and open banking integrations.
- Shared Infrastructure: Both services utilize a PostgreSQL 16 database and Redis 7 for job queuing and caching.
Sources: CLAUDE.md:12-32, README.md:105-125
High-Level Component Diagram
The following diagram illustrates the relationship between the major system components and the shared data layer.
Sources: README.md:105-135, CLAUDE.md:12-32
Tech Stack Summary
The project uses a modern TypeScript and Python stack, emphasizing strict type safety on the frontend and robust data processing on the backend.
Frontend Specifications
| Category | Technology |
|---|---|
| Framework | Next.js 16+ (App Router, Server Components) |
| Language | TypeScript (Strict Mode) |
| ORM | Drizzle (Source of Truth for Schema) |
| Auth | BetterAuth (PostgreSQL adapter) |
| UI | shadcn/ui (Stone theme, no radius) |
| State | TanStack Query |
Sources: CLAUDE.md:65-79, README.md:127-137
Backend Specifications
| Category | Technology |
|---|---|
| Framework | FastAPI |
| ORM | SQLAlchemy 2.0 (Mirrors Drizzle schema) |
| Task Queue | Celery + Redis |
| AI | OpenAI (Transaction categorization) |
Sources: CLAUDE.md:81-87, README.md:139-145
Deployment Options
Syllogic provides several deployment paths ranging from local development to production-ready cloud environments.
Local Development Setup
Developers can run the infrastructure services via Docker while running the application code locally.
- Infrastructure:
docker-compose up -d db redis - Backend: Install requirements via
pipand runuvicorn app.main:app --reload. - Frontend: Install dependencies via
pnpm installand runpnpm dev. - Database: Push schema changes using
pnpm db:push.
Sources: README.md:200-245, CLAUDE.md:144-160
Production Self-Hosting (Docker Compose)
The production bundle includes a Caddy reverse proxy for automatic TLS and a one-shot migration job.
Railway (Cloud Deployment)
Syllogic supports one-click deployment to Railway, provisioning seven distinct services: postgres, redis, backend, worker, beat, mcp, and app.
Sources: deploy/railway/README.md:3-15, README.md:183-195
Environment Configuration
Configuration is managed through environment variables for both the frontend (.env.local) and backend (.env).
Required Variables
| Variable | Description | Source |
|---|---|---|
DATABASE_URL | PostgreSQL connection string | Frontend/Backend |
BETTER_AUTH_SECRET | Secret for authentication sessions | Frontend |
INTERNAL_AUTH_SECRET | Shared secret for signed internal requests | Frontend/Backend |
APP_URL | Public URL of the application | Frontend |
REDIS_URL | Redis connection string | Backend |
Sources: README.md:320-350, deploy/compose/README.md:8-20, deploy/install/install.sh:56-75
Data Synchronization and Integration
The platform supports multiple methods for ingesting transaction data, utilizing an adapter pattern to handle various providers.
Transaction Inflow Flow
Integration Adapters
- CSV Adapters: Currently supports Revolut CSV imports with manual mapping.
- Programmatic Adapters: Designed for Plaid (US/UK/EU) and TrueLayer (UK/EU) integrations.
- AI Categorization: Uses the OpenAI API to identify merchants and categorize spending patterns.
Sources: BANK_INTEGRATION_GUIDE.md:5-40, README.md:36-45
Getting Started Summary
To get started with Syllogic, it is recommended to use the provided setup scripts for the preferred environment:
- Local Infra:
./scripts/dev-up.sh --local(runs DB/Redis in Docker, app locally). - Full Stack:
./scripts/prod-up.sh(runs all services as containers using prebuilt images).