OneSummer
Technical Architecture

Executive Summary

OneSummer is a two-sided marketplace that eliminates the annual ordeal of summer camp registration. Parents fill out a child's profile once; that profile powers applications to any participating camp. Camps receive structured, consistently-formatted applicant data instead of bespoke PDFs. This document describes the technical system that makes that exchange possible.

The architecture begins as a well-structured monolith — a single SvelteKit application backed by PostgreSQL — organized into clearly-bounded service modules from day one. This approach gives the team a single deployment unit during the critical early traction phase while preserving clear service boundaries that allow extraction into independent services when load or team structure demands it. The SOLID principles, particularly Single Responsibility and the Dependency Inversion Principle, govern module boundaries throughout.

Three technical challenges define the design above all others:

Architecture Overview

The system is a modular monolith deployed in Docker containers. The SvelteKit application serves both the server-side rendered frontend and the REST API. A single PostgreSQL instance is the system of record. An object store handles binary documents. A background job queue processes asynchronous work. Redis provides a session store and short-lived cache layer.

Request Lifecycle

Every inbound request travels the same path regardless of surface (parent UI, camp admin UI, or future API consumer).

Capability Inventory

Before selecting technologies or drawing service boundaries, the system's required capabilities are listed independently of any implementation. This prevents architecture driven by tooling familiarity rather than functional requirements.

Parent-Side Capabilities

Camp-Side Capabilities

Platform-Level Capabilities

Service Definitions

Each service is a bounded module within the SvelteKit application. Services communicate by calling each other's public TypeScript interfaces, never by reaching into each other's database queries. This enforces the Dependency Inversion Principle and makes extraction to independent processes straightforward.

API Contracts

All API routes live under /api/v1/. Authentication is via a session token in the Authorization: Bearer <token> header. All responses follow the envelope: {"data": ..., "meta": ..., "error": null} on success and {"data": null, "error": {"code": "...", "message": "..."}} on failure. All timestamps are ISO 8601 UTC.

Auth Endpoints

POST /api/v1/auth/register

Creates a parent account and sends a verification email. Does not issue a session until email is verified.

// Request
{
  "email":    "alex@example.com",
  "password": "minimum-12-chars",
  "name":     "Alex Rivera",
  "timezone": "America/New_York"
}

// 201 Created
{
  "data": {
    "parentId":          "par_01J8K...",
    "emailVerification": "pending"
  }
}

// Errors
// 409 CONFLICT       — email already registered
// 422 VALIDATION     — invalid email or weak password

POST /api/v1/auth/children

Creates a child record under the authenticated parent. Records verifiable parental consent at this moment.

// Request — requires authenticated parent session
{
  "firstName":   "Sam",
  "lastName":    "Rivera",
  "dateOfBirth": "2015-07-12",
  "consentAcknowledged": true  // must be true; COPPA consent recorded server-side
}

// 201 Created
{
  "data": {
    "childId":   "chd_01J8L...",
    "firstName": "Sam",
    "age":       10,
    "consentLogId": "clog_01J8M..."
  }
}

// Errors
// 400 BAD_REQUEST    — consentAcknowledged !== true
// 422 VALIDATION     — invalid date of birth

Vault Endpoints

PUT /api/v1/children/{childId}/profile

Upserts a child's profile fields. Parent must own the child. Fields are validated against the canonical field registry before storage.

// Request — partial update accepted (PATCH semantics via PUT)
{
  "medical": {
    "allergies":         ["peanuts", "tree nuts"],
    "epiPenRequired":    true,
    "conditions":        ["asthma"],
    "medications":       [{"name": "Albuterol", "dose": "90mcg PRN"}],
    "physicianName":     "Dr. Chen",
    "physicianPhone":    "+12125551234"
  },
  "emergency": {
    "contacts": [
      {"name": "Alex Rivera", "relationship": "parent", "phone": "+19175551234", "priority": 1}
    ]
  },
  "swimAbility": "intermediate"
}

// 200 OK
{
  "data": {
    "childId":     "chd_01J8L...",
    "updatedAt":   "2026-01-15T14:30:00Z",
    "completeness": 0.72  // fraction of canonical fields populated
  }
}

// Errors
// 403 FORBIDDEN      — authenticated parent does not own childId
// 422 VALIDATION     — field type mismatch against canonical registry

POST /api/v1/children/{childId}/grants

Grants a camp explicit read access to a child's data for a specific session. This must happen before the camp can view applicant data or before the form mapper can fetch vault data for auto-fill.

// Request
{
  "campId":    "cmp_01J9A...",
  "sessionId": "ses_01J9B...",
  "scopes": [
    "medical.allergies", "medical.epiPenRequired",
    "emergency.contacts", "swimAbility", "documents.immunization"
  ]
}

// 201 Created
{
  "data": {
    "grantId":   "grnt_01J9C...",
    "expiresAt": "2026-09-01T00:00:00Z",  // auto-expires after session end
    "scopes":    ["medical.allergies", "..."]
  }
}

Application Endpoints

POST /api/v1/applications

Initiates an application. Triggers the form mapper to resolve pre-filled data and returns the form payload with filled and missing fields identified.

// Request
{
  "childId":   "chd_01J8L...",
  "sessionId": "ses_01J9B..."
}

// 201 Created
{
  "data": {
    "applicationId": "app_01JAA...",
    "status":        "draft",
    "form": {
      "prefilled": {
        "camperFirstName":  "Sam",
        "allergyList":      "Peanuts, tree nuts",
        "emergencyContact1": "Alex Rivera — +19175551234"
      },
      "missing": [
        {"field": "tShirtSize", "required": false},
        {"field": "cabinPreference", "required": false}
      ],
      "unmapped": [
        {"field": "specialOlympicsId", "required": false}
      ]
    },
    "grantId": "grnt_01J9C..."  // auto-created grant for this session
  }
}

// Errors
// 409 CONFLICT  — active application already exists for this child + session
// 410 GONE      — session is full; offer waitlist option

POST /api/v1/applications/{applicationId}/submit

// Request — final field values (merged prefilled + parent overrides)
{
  "fields": {
    "camperFirstName":  "Sam",
    "allergyList":      "Peanuts, tree nuts",
    "tShirtSize":       "YM"
  }
}

// 200 OK
{
  "data": {
    "applicationId": "app_01JAA...",
    "status":        "submitted",
    "submittedAt":   "2026-02-14T10:05:33Z"
  }
}

// Errors
// 422 VALIDATION     — required camp fields missing
// 409 CONFLICT       — application not in draft state

Data Schema

All tables live in a single PostgreSQL 16 database. Row-Level Security (RLS) policies enforce access at the database level as a defense-in-depth measure. Migrations are managed with a versioned migration tool. The schema uses ULIDs as primary keys — lexicographically sortable, globally unique, URL-safe.

Identity Tables

Vault Tables

Camp Tables

Application Tables

Auth Model & COPPA

The authentication model is structured entirely around the COPPA constraint: children under 13 may never directly access the system. All data flows are mediated by a verified parent. This is not merely a UI limitation — it is enforced at the API, service, and database layers.

Actor Hierarchy

Session Mechanism

Sessions use opaque tokens — a cryptographically random 32-byte value stored in Redis with a 7-day TTL (sliding). The token is sent as an HttpOnly; Secure; SameSite=Strict cookie. The payload stored in Redis contains: parent ID, role, a list of child IDs the parent owns, and the session's IP and user agent for anomaly detection. There are no JWTs in the session path — this eliminates the risk of signed-but-expired-token attacks and allows instant revocation by deleting the Redis key.

Permission Model

Security Architecture

Security for OneSummer is not an afterthought — it is structurally embedded. The primary threat model is the exposure of children's medical and identity data to unauthorized parties. Every architectural decision is evaluated against this threat.

Threat Model Summary

Security Controls by Layer

Technology Stack Rationale

Each technology choice below is justified against project requirements and contrasted with at least one viable alternative. The guiding question for every choice: does this reduce complexity today without creating irreversible decisions tomorrow?

Scalability Strategy

OneSummer has an unusual traffic profile: approximately 80% of all usage occurs during a 14-week window from February through May. The architecture must handle this efficiently without paying for Year 3 infrastructure during Year 1, and without requiring a re-architecture to handle the Year 3 load.

The Seasonal Load Model

Scaling Approach by Phase

Seasonal Scaling Automation

A scheduler (cron job in Year 1, a cloud scheduler in Year 2+) scales the application replica count on a calendar schedule aligned with the registration season: scale up to peak configuration by February 1st, scale down to minimum by June 15th. This is deterministic and predictable — the traffic pattern is known a year in advance, making reactive auto-scaling a secondary mechanism rather than the primary one.

Observability

A system that cannot be debugged in production is not a finished system. Observability is designed in from day one, not bolted on when something goes wrong.

Three Pillars

Key Alerts

Deployment & CI/CD

The CI pipeline runs on every pull request: TypeScript type check, ESLint with security rules, unit tests (Vitest), integration tests against a test Postgres instance (Docker), and a Zod schema validation check to ensure no API response shape regressions. No PR merges with a failing check.

Deployments use a blue-green strategy: the new container image is deployed alongside the existing one. The load balancer shifts traffic after the health check passes. Database migrations run before the new container receives traffic. Migrations are backward-compatible by policy (additive changes only in a single migration; destructive changes in a separate migration after the old code is no longer in production).

Architecture Decision Records

The following ADRs document the key decisions made in this architecture, the context that drove them, and the trade-offs accepted. New significant technical decisions should be added here before implementation begins.