Skip to main content

Backend — Target Architecture

Bilko API — Express Backend

BookStack — Provjeri PRVO

Prije traženja bilo čega — provjeri BookStack (http://localhost:6875). Centralna baza znanja za tools, skills, hooks, agents, rules, projekte, klijente, dokumentaciju. Ako odgovor postoji tamo — NE TRAŽI dalje.

Status: NOT BUILT YET

This directory is EMPTY. The CLAUDE.md describes the target architecture. When building, follow docs/backend/API-REFERENCE.md as the implementation contract.

Target Tech Stack

  • Framework: Express + TypeScript
  • Database: PostgreSQL 15 via Prisma
  • Auth: JWT (15min access + 7d refresh) + Passport.js
  • Validation: Zod
  • Middleware: helmet, cors, rate-limit, auth-guard, zod-validation, error-handler

Route Structure

All routes under /api/v1/{resource}:

  • /api/v1/auth — login, register, refresh, logout
  • /api/v1/organizations — org CRUD
  • /api/v1/users — user management
  • /api/v1/accounts — chart of accounts
  • /api/v1/invoices — invoice CRUD
  • /api/v1/expenses — expense CRUD
  • /api/v1/transactions — transaction ledger
  • /api/v1/contacts — customer/vendor contacts
  • /api/v1/banking — bank account integration
  • /api/v1/reports — financial reports

Middleware Stack (Order Matters)

  1. helmet — Security headers
  2. cors — CORS with whitelist
  3. express.json() — Body parser
  4. rate-limit — 100 req/15min per IP
  5. auth-guard — JWT validation (protected routes)
  6. zod-validation — Request validation
  7. route-handler — Business logic
  8. error-handler — Centralized error responses

Error Response Format

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {} // optional
}

HTTP Status Codes:

  • 400 — Validation error
  • 401 — Unauthorized (missing/invalid token)
  • 403 — Forbidden (insufficient permissions)
  • 404 — Not found
  • 500 — Internal server error

Database Access

  • ORM: Prisma Client from @bilko/database package
  • Connection: Read DATABASE_URL from env
  • Transactions: Use Prisma transactions for multi-step operations
  • NEVER: Raw SQL for business logic (use for migrations only)

Authentication

  • Strategy: JWT (access + refresh tokens)
  • Access token: 15min expiry, httpOnly cookie
  • Refresh token: 7d expiry, httpOnly cookie, stored in DB
  • Password: bcrypt hash with salt rounds = 12
  • 2FA: Optional TOTP (stored in User.twoFactorSecret)

Validation Rules

All requests validated with Zod schemas:

  • Money: Must be string or number, converted to Decimal
  • Currency: 3-letter ISO code (EUR, RSD, BAM, HRK)
  • Dates: ISO 8601 format (YYYY-MM-DD)
  • UUIDs: Valid v4 UUIDs for all IDs
  • Emails: RFC 5322 compliant

Double-Entry Rules (CRITICAL)

Every financial transaction MUST:

  1. Have both debit and credit accounts
  2. Equal amounts (debit = credit)
  3. Reference the source (invoice ID, expense ID)
  4. Lock exchange rate at transaction date
  5. Create audit log entry (LoggedAction)

Development Rules

  1. NEVER hold money — This is an accounting tool, not a payment processor
  2. Immutable transactions — Once locked, NEVER modify
  3. Audit everything — All mutations logged to LoggedAction
  4. Multi-currency always — Even single-currency orgs need exchange rate support
  5. Test with real accounting scenarios — Invoice → payment → reconciliation

API Reference

Full endpoint documentation in docs/backend/API-REFERENCE.md (to be created). This file will be the contract for implementation.

Back to top