Software Architecture

Dependencies flow inward. Components depend on services; services depend on repositories; repositories depend on Prisma.

2. Service Layer in src/lib/

Keep business logic in pure functions:

// ✅ Good: Pure function in src/lib/
export function calculateBalanceTotals(totals: BalanceTotals) {
  const income = parseAmount(totals.INCOME_TAX);
  const expenses = parseAmount(totals.SALES_TAX) + parseAmount(totals.OTHER);
  return { income, expenses, balance: income - expenses };
}

// ❌ Bad: Business logic in component
function BalanceCard({ totals }) {
  // Don't compute business logic here
  const income = Number(totals.INCOME_TAX) || 0;
  // ...
}

3. Early Returns (Guard Clauses)

Reduce nesting with early returns:

// ✅ Good: Guard clauses
export async function GET(request: NextRequest) {
  const user = await getAuthUser();
  if (!user) return ApiErrors.unauthorized();

  const result = schema.safeParse(params);
  if (!result.success) return ApiErrors.validation(result.error.message);

  // Happy path at bottom
  return NextResponse.json(data);
}

// ❌ Bad: Deeply nested
export async function GET(request: NextRequest) {
  const user = await getAuthUser();
  if (user) {
    const result = schema.safeParse(params);
    if (result.success) {
      // ...deeply nested
    }
  }
}

4. Domain Module Structure

Each domain (like receipt/) should follow this pattern:

src/lib/receipt/
├── index.ts                    # Public API exports
├── receipt-extraction.ts       # Core extraction logic
├── receipt-ocr.ts              # OCR parsing
├── receipt-llm.ts              # LLM extraction
├── receipt-storage.ts          # File storage
├── receipt-job-repository.ts   # Database access
├── receipt-jobs-service.ts     # Orchestration service
└── __tests__/                  # Co-located tests
    ├── receipt-extraction.test.ts
    └── receipt-storage.test.ts

5. Repository Pattern

Separate data access from business logic:

// Repository: Data access only
export async function findPendingJobs(userId: string) {
  return prisma.receiptJob.findMany({
    where: { userId, status: 'QUEUED' },
    orderBy: { createdAt: 'asc' },
  });
}

// Service: Business logic using repository
export async function processNextJob(userId: string) {
  const jobs = await findPendingJobs(userId);
  if (jobs.length === 0) return null;
  
  const job = jobs[0];
  // Business logic here...
}

Where Does New Code Go?

Testing Strategy

• Unit tests: Pure functions in src/lib/ (Vitest)
• Component tests: React components with mocked APIs (Vitest)
• E2E tests: Full user flows (Playwright in e2e/)

Co-locate tests in __tests__/ folders near the code they test.

Common Patterns

API Route Template

import { NextRequest, NextResponse } from "next/server";
import { getAuthUser, ApiErrors, getRequestId, attachRequestId } from "@/lib/api-utils";
import { checkRateLimit, RateLimitConfig, rateLimitedResponse } from "@/lib/rate-limit";
import { mySchema } from "@/lib/schemas";

export async function GET(request: NextRequest) {
  const requestId = getRequestId(request);
  
  const user = await getAuthUser();
  if (!user) return attachRequestId(ApiErrors.unauthorized(), requestId);

  const rateLimitResult = await checkRateLimit(user.id, RateLimitConfig.api);
  if (!rateLimitResult.success) {
    return attachRequestId(rateLimitedResponse(rateLimitResult), requestId);
  }

  // Validation, business logic, response...
}

Component with API Data

"use client";

import useSWR from "swr";
import { fetcher } from "@/lib/fetcher";

export function MyComponent() {
  const { data, error, isLoading } = useSWR("/api/resource", fetcher);
  
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorState />;
  
  return <div>{/* Render data */}</div>;
}