Two-Service Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Syllogic personal finance platform is built on a two-service architecture designed to separate user-facing operations from intensive data processing tasks. This architecture consists of a Next.js frontend and a Python-based backend, both of which communicate through a shared PostgreSQL database and a Redis-backed task queue.
Sources: README.md:65-81, CLAUDE.md:5-10
Architectural Overview
The system divides responsibilities between two primary services to ensure responsive user interfaces while maintaining a robust pipeline for financial data enrichment.
Service Responsibilities
| Service | Technology | Primary Responsibilities |
|---|---|---|
| Frontend | Next.js 16+ (App Router) | UI/UX, Authentication, CRUD operations via Server Actions, Drizzle ORM management. |
| Backend | Python (FastAPI) | AI transaction enrichment, merchant identification, background cron jobs, bank integrations. |
| Infrastructure | PostgreSQL & Redis | Shared data storage (PostgreSQL) and message brokering for background tasks (Redis). |
Sources: CLAUDE.md:5-10, README.md:83-100
System Data Flow
The following diagram illustrates the high-level relationship between the user, the two primary services, and the shared infrastructure.
Note: Both services share a single PostgreSQL database as the primary source of truth.
Sources: CLAUDE.md:12-25, README.md:68-81
Shared Infrastructure
PostgreSQL Database
Both services connect to the same PostgreSQL 16 instance. The Drizzle ORM schema in the frontend is considered the source of truth for the database structure. The Python backend utilizes SQLAlchemy 2.0 to mirror this schema for its operations.
Sources: CLAUDE.md:9, README.md:98, deploy/compose/docker-compose.yml:7-21
Redis and Celery
Redis 7 serves as the message broker for the backend's asynchronous task system. This system includes:
- Celery Worker: Executes transaction enrichment, categorization, and bank sync tasks.
- Celery Beat: Handles scheduled daily syncs and recurring background jobs.
Sources: CLAUDE.md:66-73, README.md:100, deploy/compose/docker-compose.yml:23-32
Service Details
Frontend (Next.js)
The frontend manages all user interactions and authentication. It uses BetterAuth for session management and Drizzle ORM with Server Actions for direct database mutations.
- Authentication: Protected routes verify sessions via BetterAuth before allowing access to data.
- Data Operations: Mutations are handled via
"use server"actions that interact with the shared database. - Proxying: Next.js can act as an API proxy to the backend for specific routes.
Sources: CLAUDE.md:37-58, frontend/package.json:28-30
Backend (Python/FastAPI)
The backend focuses on data-heavy tasks and external integrations. It provides API endpoints for transaction management and stats.
- Enrichment: Uses OpenAI to identify merchants and categorize transactions.
- Integrations: Implements an adapter pattern for bank services like Plaid or TrueLayer.
- MCP Server: Includes a FastMCP server for programmatic access to financial data.
Sources: README.md:27-32, BANK_INTEGRATION_GUIDE.md:6-15, deploy/compose/docker-compose.yml:85-104
Communication and Security
Communication between the services and external clients is secured through internal secrets and signed requests.
| Variable | Description |
|---|---|
DATABASE_URL | Shared connection string for PostgreSQL access. |
INTERNAL_AUTH_SECRET | Shared secret used to sign and verify internal app-to-backend requests. |
BETTER_AUTH_SECRET | Secret used by the frontend to sign authentication sessions. |
REDIS_URL | Connection string for the Celery task queue. |
Sources: CLAUDE.md:144-154, deploy/railway/docker-compose.yml:106-115
Deployment and Orchestration
The two-service architecture is orchestrated using Docker Compose across various environments, ensuring that environment variables for shared access (like the database) are consistent across all containers.
Note: Successful database migration is a prerequisite for starting the application and backend services.
Sources: deploy/compose/docker-compose.yml:45-70, deploy/railway/docker-compose.yml:92-102
Conclusion
The Two-Service Architecture of Syllogic leverages the strengths of Next.js for user experience and Python for data processing. By sharing a database and using a centralized task queue, the system maintains data consistency while allowing for complex, AI-driven financial analysis to occur in the background without impacting frontend performance.