Technical Architecture

0 Architecture Principles

These principles govern every technical decision in this document. When trade-offs arise, they serve as the tiebreaker. Any deviation from these principles requires an explicit ADR.

Layered Separation of Concerns

Every feature is implemented across clearly separated layers. No layer reaches across its boundary into another layer's responsibility.

1 System Overview

Groundwork is a two-sided platform connecting homeowners and contractors within a shared project workspace. The architecture is a monolithic API (intentionally — see ADR-07) deployed on Fly.io, a SvelteKit frontend on Netlify, PostgreSQL on Neon for all relational data, Cloudflare R2 for document storage, and Fly.io workers for background integration polling.

Key Architectural Decisions Visible in This Diagram

2 Frontend Architecture

Rendering Strategy

SvelteKit supports multiple rendering modes per route. Groundwork uses a deliberate split: SSR for public-facing pages (SEO and first-contentful-paint), and client-side SPA rendering for the authenticated application. This gives the landing page sub-1-second LCP without sacrificing the interactive richness of the project dashboard.

Component Architecture

Components follow the Container / Presentational pattern. No business logic in components. Data fetching happens in +page.ts load functions or via stores — never inline in component markup.

// Directory structure — feature-first, not type-first
src/
  lib/
    components/
      ui/               // Button, Badge, Modal, Toast — design system atoms
      project/          // ProjectCard, ProjectHeader, MilestoneTimeline
      change-order/     // ChangeOrderForm, ChangeOrderStatus
      payment/          // PaymentSchedule, PaymentRow
      document/         // DocumentUploader, DocumentList
      permit/           // PermitStatus, PermitTimeline
    stores/
      project.ts        // Writable<Project> — current project context
      notifications.ts  // real-time notification queue
      session.ts        // User session, role, permissions
    api/
      client.ts         // Typed fetch wrapper — all API calls go through here
      projects.ts       // Project CRUD functions
      milestones.ts
      documents.ts
    utils/
      format.ts         // Currency, date formatting — pure functions
      validate.ts       // Client-side validation schemas (Zod)
  routes/
    (public)/           // SSR group
    (app)/              // Auth-guarded CSR group

State Management

Svelte's built-in stores are sufficient for Groundwork's data model. No Zustand, Redux, or Pinia. The session store holds the current user. The project store holds the current project (populated by the route's load function). Notifications arrive via Server-Sent Events and push to the notifications store.

Performance Budget

Achieving the performance budget:

• SvelteKit compiles away the framework — no virtual DOM, minimal runtime. Landing page JS is typically 20–40kb gzipped.
• Images served through Cloudflare's image resizing — correct size and format (WebP/AVIF) per viewport.
• Fonts loaded via font-display: swap with preconnect hints. Only 2 font families, 3 weights each.
• Route-level code splitting is automatic in SvelteKit — the project dashboard doesn't load the admin panel's code.
• SvelteKit's preload strategy: link hover triggers prefetch of the next route's data.

Security Considerations — Frontend

• CSRF protection: Session cookies use SameSite=Strict. All state-mutating requests include a CSRF token from the session, validated server-side.
• Content Security Policy: Strict CSP header from Netlify — no inline scripts, no eval, allowed hosts enumerated explicitly.
• Sensitive data: PII (addresses, contractor license numbers) is never stored in localStorage or sessionStorage — only in memory. Refresh clears it; the API re-fetches as needed.
• Input sanitization: All text content rendered via Svelte's {} binding (not {@html}) — auto-escaped, XSS-safe by default.

3 Backend Architecture

Framework: Hono on Node.js (Fly.io)

The API is built with Hono, a lightweight TypeScript-first HTTP framework with excellent performance characteristics and middleware composability. It runs on Node.js on a Fly.io VM (not serverless — see ADR-07). The codebase is organized as a modular monolith: separate router files per domain, shared middleware, dependency injection via closure rather than a DI container.

Why REST over GraphQL — see ADR-05. Short version: Groundwork's data model is relational, access patterns are predictable CRUD, and GraphQL's N+1 risks and schema complexity add cost without benefit at this scale.

Key API Endpoints

Authentication: Session Cookies (not JWT)

See ADR-03 for the full rationale. Sessions are stored server-side in Postgres (with a Redis cache for fast lookup). The client receives only an opaque session ID in an HttpOnly; Secure; SameSite=Strict cookie. Sessions expire after 24 hours of inactivity and are invalidated immediately on logout.

// Session table — stored in Postgres, cached in Redis
CREATE TABLE sessions (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  last_seen   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  expires_at  TIMESTAMPTZ NOT NULL,
  ip_address  INET,
  user_agent  TEXT
);

-- Redis key: "session:{id}" → JSON(user_id, role, expires_at)
-- TTL: 24 hours, refreshed on each request

RBAC: Role-Based Access Control

Three roles: homeowner, contractor, admin. Role is stored on the project_members join table (not globally on the user) — a user can be a homeowner on one project and a contractor on another. The middleware resolves the caller's role within the requested project before routing.

Rate Limiting Strategy

Rate limits are enforced at the API middleware layer using a sliding window counter stored in Redis (Upstash). Three tiers:

• Global per-IP: 300 req/min for all authenticated requests. Blocks volumetric abuse before hitting business logic.
• Endpoint-specific: Tighter limits on destructive or expensive endpoints (see table above). Authentication endpoints are the most restrictive — 5 attempts/min/IP with exponential backoff.
• Per-user: 60 req/min across all authenticated requests for a given user ID, regardless of IP. Prevents credential-stuffed accounts from being used as scrapers.

4 Data Architecture

Primary Schema: PostgreSQL (Neon)

All relational data lives in a single PostgreSQL database hosted on Neon. The schema below covers the 7 primary entities plus supporting tables. Row Level Security is enabled on all tables containing project data.

Caching Strategy: When to Use Redis vs. Postgres

Not everything needs to be cached. Cache when: the data is read far more often than it changes, computing it is expensive, or latency for stale data is acceptable. Do not cache when: correctness is critical (payment amounts, audit events) or the dataset fits in a single Postgres query.

Real-Time: PostgreSQL LISTEN/NOTIFY

PostgreSQL's built-in pub/sub mechanism handles real-time project updates without a separate WebSocket server or message broker. A Postgres trigger fires on writes to milestones, change_orders, and permits — emitting a notification on a channel named project:{project_id}. The API server maintains a single persistent Postgres connection per project that has active SSE subscribers, forwarding notifications to those clients.

-- Trigger on milestone update
CREATE OR REPLACE FUNCTION
  notify_project_change()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM pg_notify(
    'project:' || NEW.project_id,
    json_build_object(
      'entity', TG_TABLE_NAME,
      'id',     NEW.id,
      'event',  TG_OP
    )::text
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER milestone_notify
AFTER INSERT OR UPDATE ON milestones
FOR EACH ROW EXECUTE FUNCTION
  notify_project_change();

Document Storage: Cloudflare R2

Documents (contracts, permits, invoices, photos) are stored in Cloudflare R2. The flow is a two-step upload: the API generates a presigned PUT URL (valid 15 minutes), the client uploads directly to R2 (bypassing the API entirely), then the client POSTs a confirmation to the API which persists the metadata. This keeps large binaries off the application server.

5 Integration Architecture

City Permit APIs

This is the most technically challenging integration. There is no standard API — every municipality has its own portal, data model, and access method. Groundwork's Year 1 target (one city) allows for a focused adapter. Year 2 requires a pluggable adapter pattern.

interface PermitAdapter {
  fetchByAddress(
    address: string,
    city: string,
    state: string
  ): Promise<PermitRecord[]>;

  fetchByPermitNumber(
    id: string
  ): Promise<PermitRecord>;

  normalizeStatus(
    raw: string
  ): PermitStatus;
}

Delivery Tracking

Carrier APIs (UPS, FedEx, USPS) provide REST APIs with reasonable documentation. Groundwork tracks deliveries linked to project milestones (e.g., "lumber delivery" before "framing" milestone).

License Verification

Contractor license verification is the most fragile integration. Most state databases offer no API — they require either screen scraping of a public search form or access to a third-party aggregator.

Email & SMS (Notifications)

Outbound notifications use Resend for transactional email (excellent deliverability, TypeScript SDK, generous free tier) and Twilio for SMS on critical events (milestone payment due, change order requiring approval within 48h).

6 Background Processing

Background jobs run as separate Fly.io worker machines. They consume jobs from the Postgres job_queue table using the SKIP LOCKED pattern — multiple workers can run concurrently without stepping on each other, and jobs are never lost (they live in the database, not in memory). See ADR-04 for the trade-off analysis.

-- Worker claim query — safe for concurrent workers
UPDATE job_queue
SET
  status    = 'processing',
  locked_at = NOW(),
  attempts  = attempts + 1
WHERE id = (
  SELECT id FROM job_queue
  WHERE  status = 'pending'
    AND  run_at <= NOW()
    AND  attempts < max_attempts
  ORDER BY run_at ASC
  LIMIT 1
  FOR UPDATE SKIP LOCKED
)
RETURNING *;

Job Types

Contract Health Score Algorithm

The ContractHealthScore is a 0–100 composite score computed by the health.compute worker. It is the most business-critical computation in the system. The algorithm is deterministic and testable as a pure function.

7 Security Architecture

Authentication Flow

Data Encryption

Multi-Tenant Isolation: Row Level Security

Row Level Security (RLS) is the last line of defense for multi-tenant data isolation. Even if the application layer has a bug that constructs an incorrect query, the database itself will not return data from another tenant's project.

-- Enable RLS on all project-scoped tables
ALTER TABLE milestones     ENABLE ROW LEVEL SECURITY;
ALTER TABLE change_orders  ENABLE ROW LEVEL SECURITY;
ALTER TABLE documents      ENABLE ROW LEVEL SECURITY;
ALTER TABLE permits        ENABLE ROW LEVEL SECURITY;

-- Policy: user can only see milestones from their projects
CREATE POLICY milestones_member_policy
ON milestones FOR ALL TO app_user
USING (
  project_id IN (
    SELECT project_id
    FROM   project_members
    WHERE  user_id = current_setting('app.current_user_id')::uuid
  )
);

-- API sets the user context before each query
-- SELECT set_config('app.current_user_id', $1, true)

-- Separate DB role for workers — cannot write to audit_events
CREATE ROLE app_worker;
GRANT SELECT, UPDATE ON job_queue TO app_worker;
GRANT SELECT, INSERT ON permits   TO app_worker;
GRANT SELECT, UPDATE ON projects  TO app_worker;

PII Inventory

Security Checklist by Threat Vector

8 Scaling Strategy

Groundwork is designed to start simple and scale predictably. The architectural choices in Year 1 deliberately avoid premature optimization while maintaining clear paths to Year 3 capacity.

Database Scaling Path

The most important scaling risk is the database. The strategy is to exhaust Postgres vertical scaling before introducing horizontal complexity.

API Scaling: Stateless by Design

The API server is stateless — all session state is in Redis, all data is in Postgres. Adding a second or tenth API machine requires zero coordination. Fly.io's built-in load balancer distributes traffic across instances. The SSE stream connections are sticky (Fly.io session affinity) to avoid the complexity of cross-instance event broadcasting.

Cache Strategy: TTLs and Invalidation

Cache invalidation is the root of many production bugs. The strategy here is explicit: cache entries are invalidated on write, not relying on TTL expiry for correctness. TTLs are a safety net, not the primary invalidation mechanism.

9 Observability

A system that cannot be debugged in production is incomplete. Observability is built in from day one. Every request, every background job, and every integration failure is traceable.

Structured Logging

All application logs are written to stdout as newline-delimited JSON (NDJSON) using Pino. Log levels: error, warn, info, debug. Production defaults to info. Fly.io captures stdout and streams to a log drain.

// Every log entry includes standard fields
{
  "level":      "info",
  "time":       1744000000000,
  "pid":        1234,
  "requestId":  "req_01J...",   // Ulid — unique per request
  "userId":     "usr_01J...",   // null if unauthenticated
  "projectId":  "proj_01J...",  // null if not project-scoped
  "method":     "PATCH",
  "path":       "/projects/abc/milestones/xyz",
  "status":     200,
  "latencyMs":  42,
  "msg":        "milestone updated"
}

Key Metrics

Error Tracking: Sentry

Sentry captures unhandled exceptions and explicit error calls in both the frontend and backend. Configuration:

• Source maps uploaded during CI deploy — Sentry shows original TypeScript, not compiled JS
• PII scrubbing enabled in Sentry SDK (send_default_pii: false)
• Alerts: any new error issue triggers a Slack notification to #eng-alerts
• Performance tracing: 10% of transactions sampled (1% in Year 1 to stay within free tier)
• Integration failures (permit API, carrier API) logged as Sentry issues with breadcrumbs

Uptime Monitoring

UptimeRobot (free tier): HTTP monitors on GET /health (API) and the Netlify frontend. 5-minute check interval. Alerts via email + Slack.

The GET /health endpoint performs a lightweight check:

// Health check — fast, meaningful
GET /health → {
  "status": "ok",
  "db":     "ok",   // SELECT 1 against Neon
  "redis":  "ok",   // PING against Upstash
  "uptime": 86400  // seconds since last restart
}

On-Call Runbooks

Each Sentry alert links to a runbook in /docs/runbooks/. Every recurring alert must have a runbook before the system launches. Runbooks include: alert description, probable causes, diagnostic queries, resolution steps, and escalation path. This is non-negotiable — alerts without runbooks create panic, not resolution.

10 Architecture Decision Records

Each decision below documents context, the decision taken, and the trade-offs accepted. These are living records — if a decision is revisited, the ADR is updated with the date and reason.

Decision Summary