Development Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides a comprehensive overview of the Syllogic personal finance application's architecture, development patterns, and technical specifications. It is designed to assist developers in understanding the two-service architecture, data synchronization pipelines, and the tech stack required to contribute to the project.
Sources: CLAUDE.md:4-8, README.md:94-118
System Architecture
The application utilizes a two-service architecture centered around a shared PostgreSQL database. The Frontend, built with Next.js, handles UI, authentication, and standard CRUD operations. The Backend, powered by FastAPI, manages complex data pipelines, transaction enrichment, and background jobs.
The architecture ensures that Drizzle ORM remains the source of truth for the database schema while allowing the Python backend to perform heavy-duty data processing.
Sources: CLAUDE.md:12-29, README.md:94-110
Tech Stack & Tooling
Frontend Development
The frontend is a TypeScript-based Next.js application using the App Router. It follows a strict "Server Actions" pattern for all data mutations.
| Category | Technology | Notes |
|---|---|---|
| Framework | Next.js 16+ | App Router, Server Components |
| ORM | Drizzle | Source of truth for DB schema |
| Auth | BetterAuth | PostgreSQL adapter |
| UI | shadcn/ui | Stone theme, No radius |
| State | TanStack Query | Manages server state |
| Tables | TanStack Table | Integrated via shadcn/ui |
Sources: CLAUDE.md:44-58, frontend/package.json:28-56
Backend & Infrastructure
The backend provides the API for data integrations and handles background tasks via Celery.
| Category | Technology | Notes |
|---|---|---|
| Framework | FastAPI | Data pipeline and internal API |
| ORM | SQLAlchemy 2.0 | Mirrors Drizzle schema |
| Jobs | Celery + Redis | Scheduled tasks and async processing |
| Database | PostgreSQL 16 | Shared between services |
| Cache | Redis 7 | Job queues and caching |
Sources: CLAUDE.md:61-75, deploy/compose/docker-compose.yml:1-55
Core Development Patterns
Data Operations
Developers must use Next.js Server Actions for all frontend mutations. These actions interact directly with the database using the Drizzle client.
"use server";
import { db } from "@/lib/db";
import { transactions } from "@/lib/db/schema";
export async function updateCategory(txId: string, categoryId: string) {
await db.update(transactions)
.set({ categoryId })
.where(eq(transactions.id, txId));
revalidatePath("/transactions");
}
Sources: CLAUDE.md:83-96
Transaction Import Pipeline
The application supports a sophisticated CSV import pipeline involving AI-assisted column mapping and duplicate detection.
Security and Internal Auth
Communication between the Frontend and Backend services is secured using signed internal authentication.
- Shared Secret:
INTERNAL_AUTH_SECRETmust be set in both environments. - Request Signing: The Frontend signs requests to the Backend using
createInternalAuthHeaders.
Sources: frontend/lib/actions/csv-import.ts:792-796, deploy/compose/docker-compose.yml:68-71
Bank Integration Architecture
The system uses an Adapter Pattern to facilitate bank synchronization. Currently, the application supports manual CSV imports (Revolut) but is architected for programmatic integrations like Plaid or TrueLayer.
| Integration | Status | File Path |
|---|---|---|
| Revolut CSV | Implemented | frontend/lib/actions/csv-import.ts |
| Plaid | Ready to implement | backend/app/integrations/plaid_adapter.py |
| TrueLayer | Ready to implement | backend/app/integrations/truelayer_adapter.py |
Sources: BANK_INTEGRATION_GUIDE.md:5-20, BANK_INTEGRATION_GUIDE.md:104-121
Development Commands
Common CLI Tasks
| Task | Command | Directory |
|---|---|---|
| Start Frontend Dev | pnpm dev | /frontend |
| Push Schema to DB | pnpm db:push | /frontend |
| Generate Migrations | pnpm db:generate | /frontend |
| Start Backend API | uvicorn app.main:app --reload | /backend |
| Start Celery Worker | celery -A worker.celery_app worker | /backend |
| Start Infra (Docker) | docker-compose up -d postgres redis | Project Root |
Sources: CLAUDE.md:129-145, README.md:195-208
Conclusion
Syllogic's development environment is built to balance the rapid UI development of Next.js with the robust data processing capabilities of Python. By strictly following the shared database schema (Drizzle as source of truth) and utilizing Server Actions for frontend logic, developers can maintain a consistent and scalable codebase.
Sources: CLAUDE.md:8-10, README.md:329-335