CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

finan-track is a cloud-agnostic invoice processing and financial tracking application with WhatsApp integration via Kapso.ai. The architecture follows a layered functional style optimized for solo development—no classes, no over-abstraction, just clean TypeScript functions.

Key Principles

Cloud-agnostic: Same code runs on AWS, Cloudflare, Docker, or any platform
Layered architecture: Simple functional layers (routes → services → repositories → libraries)
Configuration-driven: Switch providers (S3/R2/MinIO, SQS/RabbitMQ) via environment variables
Pragmatic over dogmatic: Use the simplest solution that works

Architecture

Layered Functional Structure

Routes (HTTP) → Services (Business Logic) → Repositories (Data) → Libraries (External Services)

Key architectural files to read:

```
LAYERED_ARCHITECTURE.md
```
- Main architecture overview (START HERE)
```
docs/PHASE_1_LAYERED.md
```
- Detailed implementation guide
```
docs/ARCHITECTURE_COMPARISON.md
```
- Why we chose this architecture
```
docs/APP_INFRA_SEPARATION.md
```
- Application vs infrastructure separation
```
docs/ULTRACITE_SETUP.md
```
- Code quality and linting setup

Directory Structure

app/
├── api/                    # HTTP routes and middleware (Fastify)
├── services/               # Business logic (pure functions)
├── repositories/           # Data access layer (PostgreSQL)
├── jobs/                   # Background workers
├── lib/                    # External service clients (cloud-agnostic)
│   ├── storage.ts         # S3/R2/MinIO client
│   ├── queue.ts           # SQS/RabbitMQ client
│   ├── whatsapp.ts        # Kapso.ai client
│   ├── ocr.ts             # OCR service client
│   └── cache.ts           # Redis/KV client
├── types/                  # TypeScript types
├── utils/                  # Helper functions
├── config/                 # Configuration management (Zod schemas)
└── frontend/               # Dashboard UI (React + Vite + Tailwind)

infra/terraform/            # Infrastructure as Code (Terraform)
deployments/docker/         # Docker Compose for local dev
migrations/                 # Database migrations

Technology Stack

API: Fastify
Database: PostgreSQL (cloud-agnostic, works anywhere)
Storage: S3-compatible (AWS S3, Cloudflare R2, MinIO)
Queue: SQS, RabbitMQ, or Cloudflare Queues
Cache: Redis or memory
WhatsApp: Kapso.ai integration
Frontend: React + Vite + Tailwind CSS + Tan Stack Query
Language: TypeScript (functional style, no classes)

Development Commands

Local Development

# Start all services (PostgreSQL, MinIO, RabbitMQ, Redis) in Docker
npm run dev:all

# Start API server with hot reload
npm run dev

# Start background worker
npm run dev:worker

# Start frontend (in app/frontend/)
cd app/frontend && npm run dev

Code Quality

# Format and auto-fix with Ultracite (replaces ESLint + Prettier)
npm run format

# Check code quality and complexity
npm run lint

# TypeScript type checking
npm run typecheck

# Run all checks (typecheck + lint + test)
npm run check

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Build & Deploy

# Build for production
npm run build

# Start production server
npm run start

# Start production worker
npm run start:worker

Database

# Run database migrations
npm run migrate

# Seed database with test data
npm run seed

Docker

# Start all local services
npm run docker:up

# Stop all services
npm run docker:down

# Build Docker image
npm run docker:build

Code Patterns

Functional Style - No Classes

All code uses pure functions instead of classes. This makes the codebase simpler, more testable, and easier to understand.

Configuration (app/config/env.ts)

Use Zod for environment variable validation
Export
```
loadConfig()
```
to initialize and
```
getConfig()
```
to access
Fail fast with descriptive errors if config is invalid

Libraries (app/lib/*.ts)

Use singleton pattern with module-level variables (e.g.,
```
let s3Client: S3Client
```
)
Provide
```
init*()
```
function to initialize and
```
get*()
```
function to access
Support multiple providers via configuration (e.g.,
```
QUEUE_TYPE=sqs|rabbitmq|memory
```
)

Example structure:

let client: Client;

export function initClient(): Client {
  if (client) return client;
  // Initialize client
  return client;
}

function getClient(): Client {
  if (!client) initClient();
  return client;
}

export async function doSomething(): Promise<Result> {
  const c = getClient();
  // Use client
}

Repositories (app/repositories/*.ts)

Use named functions for data access (no classes)
Import
```
query
```
,
```
queryOne
```
,
```
transaction
```
from
```
./db.ts
```
Return domain types (from
```
app/types/
```
)
Keep SQL queries clean and well-formatted

Naming convention:

```
createX(data)
```
- Insert new record
```
getXById(id)
```
- Get by ID
```
listXs(filters)
```
- List with filters
```
updateX(id, data)
```
- Update record
```
deleteX(id)
```
- Delete record (prefer soft delete)

Services (app/services/*.ts)

Contains business logic (orchestrates repositories and libraries)
Pure functions that accept data and return results
Handle errors gracefully (try/catch with meaningful messages)
No direct database access—use repositories

Example structure:

import * as repo from '../repositories/some-repo';
import * as lib from '../lib/some-lib';

export async function doBusinessLogic(input: Input): Promise<Output> {
  // 1. Validate input
  // 2. Call repositories and libraries
  // 3. Apply business rules
  // 4. Return result
}

Routes (app/api/routes/*.ts)

Use Fastify route handlers
Keep routes thin—delegate to services
Use Zod for request validation
Return structured JSON responses

Example structure:

import { FastifyInstance } from 'fastify';
import * as service from '../../services/some-service';

export async function routes(app: FastifyInstance) {
  app.get('/:id', async (request, reply) => {
    const { id } = request.params;
    const result = await service.get(id);
    return result;
  });
}

Cloud-Agnostic Libraries

The

app/lib/

directory contains cloud-agnostic clients that work with multiple providers by checking environment variables.

Example: Storage (

app/lib/storage.ts

)

Uses AWS SDK S3 client
Works with AWS S3, Cloudflare R2, MinIO
Configured via
```
STORAGE_ENDPOINT
```
,
```
STORAGE_BUCKET
```
, etc.

Example: Queue (

app/lib/queue.ts

)

Supports SQS, RabbitMQ, in-memory queue
Provider determined by
```
QUEUE_TYPE
```
env var
Exposes unified API:
```
enqueue()
```
,
```
dequeue()
```
,
```
consume()
```

Example: Database (

app/repositories/db.ts

)

Uses PostgreSQL client (pg)
Works with AWS RDS, Neon, local PostgreSQL
Configured via
```
DATABASE_URL
```

No Dependency Injection Container

This project uses simple imports instead of a DI container. Functions are imported directly where needed.

// ✅ Good - Direct imports
import * as storage from '../lib/storage';
import * as queue from '../lib/queue';

export async function processFile() {
  await storage.uploadFile('key', buffer);
  await queue.enqueue('jobs', { id: 123 });
}

// ❌ Avoid - DI container
const container = new Container();
container.bind('storage').to(StorageService);
// ... unnecessary complexity

Error Handling

Use try/catch in services and routes
Return structured errors:
```
{ success: boolean, error?: string }
```
Log errors with context using the logger
Never silently swallow exceptions

Testing Approach

Write unit tests for services and utils (pure functions are easy to test)
Write integration tests for repositories (use test database)
Mock libraries in tests (e.g., mock
```
storage.uploadFile()
```
)
Use Vitest for testing (fast, modern, TypeScript-first)

Linting and Formatting

This project uses Ultracite (not ESLint + Prettier).

What is Ultracite?

Zero-configuration linter and formatter built on Biome (Rust-based)
Replaces ESLint + Prettier with a single tool
50-100x faster than ESLint
Enforces complexity limits, type safety, import organization automatically

Key Commands

# Format and auto-fix all issues
npm run format

# Check for issues (no auto-fix)
npm run lint

What Ultracite Enforces

Complexity limits (prevents deeply nested code)
Type safety (no implicit any, explicit return types)
Import organization (auto-sorted, no unused)
Code formatting (consistent style)
Accessibility (a11y rules for React)

Important: When making changes, run

npm run check

before committing. This runs typecheck + lint + tests.

See

docs/ULTRACITE_SETUP.md

for details.

Theme Customization

The frontend uses a configurable theme system powered by Tailwind CSS. Colors can be customized by editing

theme.config.json

Color Families

```
primary
```
- Main brand color
```
secondary
```
- Secondary UI elements
```
accent
```
- Accent highlights
```
success
```
,
```
warning
```
,
```
error
```
- State colors
```
neutral
```
- Text and neutral elements

Applying Changes

After modifying

theme.config.json

, rebuild the frontend:

cd app/frontend && npm run build

Environment Variables

All configuration is done via environment variables. See

.env.example

for all available options.

Key Variables

Database:

```
DATABASE_URL
```
- PostgreSQL connection string

Storage (S3-compatible):

```
STORAGE_ENDPOINT
```
- S3 endpoint (e.g.,
```
http://localhost:9000
```
for MinIO)
```
STORAGE_BUCKET
```
- Bucket name
```
STORAGE_ACCESS_KEY
```
,
```
STORAGE_SECRET_KEY
```
- Credentials

Queue:

```
QUEUE_TYPE
```
-
```
sqs
```
,
```
rabbitmq
```
, or
```
memory
```
```
QUEUE_URL
```
- Queue connection string

WhatsApp:

```
KAPSO_API_KEY
```
- Kapso.ai API key
```
KAPSO_WEBHOOK_SECRET
```
- Webhook secret

OCR:

OCR_PROVIDER

tesseract

textract

, or

cloudflare-ai

Switching Providers

To switch from local MinIO to AWS S3, just update env vars:

# Local (MinIO)
STORAGE_ENDPOINT=http://localhost:9000
STORAGE_BUCKET=invoices

# Production (AWS S3)
STORAGE_ENDPOINT=https://s3.amazonaws.com
STORAGE_BUCKET=my-prod-bucket

No code changes needed! The application is fully cloud-agnostic.

Working with the Codebase

Before Starting a Feature

Read
```
LAYERED_ARCHITECTURE.md
```
to understand the structure
Find similar features in the codebase (e.g., study existing services/repositories)
Follow the same patterns and conventions

When Writing Code

Keep functions small and focused (single responsibility)
Use TypeScript types everywhere (no
```
any
```
)
Write descriptive function and variable names
Add JSDoc comments for public functions
Prefer early returns over nested conditionals

When Adding Dependencies

Check if a simpler solution exists first
Prefer lightweight, focused libraries over heavy frameworks
Document why the dependency is needed

When Stuck

Follow the "3 attempts rule":

Try to implement the feature
If blocked, research 2-3 alternative approaches
Try the most promising approach
If still stuck, document the issue and ask for help

Never make more than 3 attempts without stopping to reassess.

Infrastructure vs Application

This repository separates application code (

app/

) from infrastructure (

infra/

Application = Cloud-agnostic code (same code runs anywhere)
Infrastructure = Terraform provisions resources (DB, storage, queues)
Bridge = Environment variables (infra outputs → app inputs)

Current Phase

Phase 1: Building the application locally using Docker Compose

Phase 2 (later): Set up cloud infrastructure with Terraform

See

docs/APP_INFRA_SEPARATION.md

for details.

Important Reminders

DO

✅ Use functions, not classes
✅ Keep it simple and pragmatic
✅ Follow existing patterns in the codebase
✅ Write tests for new features
✅ Run
```
npm run check
```
before committing
✅ Use early returns to reduce nesting
✅ Make libraries cloud-agnostic via configuration

DON'T

❌ Don't create classes (use functions)
❌ Don't over-abstract (keep it simple)
❌ Don't add DI containers (use direct imports)
❌ Don't hardcode provider-specific logic (use env vars)
❌ Don't bypass
```
npm run check
```
(it catches bugs)
❌ Don't nest code deeply (Ultracite will complain)

Quick Reference

File Locations

Configuration:
```
app/config/env.ts
```
Database connection:
```
app/repositories/db.ts
```
Cloud-agnostic libraries:
```
app/lib/*.ts
```
Business logic:
```
app/services/*.ts
```
Data access:
```
app/repositories/*.ts
```
HTTP routes:
```
app/api/routes/*.ts
```
Types:
```
app/types/*.ts
```

Common Tasks

Add new route: Create file in
```
app/api/routes/
```
, register in
```
app/api/server.ts
```
Add new service: Create file in
```
app/services/
```
, import in routes
Add new repository: Create file in
```
app/repositories/
```
, import in services
Add new type: Create file in
```
app/types/
```
, export from
```
app/types/index.ts
```
Add migration: Create
```
.sql
```
file in
```
migrations/
```

Documentation

Architecture:
```
LAYERED_ARCHITECTURE.md
```
Implementation guide:
```
docs/PHASE_1_LAYERED.md
```
Architecture comparison:
```
docs/ARCHITECTURE_COMPARISON.md
```
App/infra separation:
```
docs/APP_INFRA_SEPARATION.md
```
Linting/formatting:
```
docs/ULTRACITE_SETUP.md
```

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password