Architecture Diagrams

Three tiers: a client that renders the map and every screen, a stateless Spring Boot API that owns logic, authorization, and persistence, and Postgres with PostGIS. The client loads tiles from Mapbox directly; the API talks to Google only during sign-in.

No queues, caches, workers, or microservices. Each adds a failure mode we cannot afford in 14 weeks.

C4 Level 1: System Context

Who uses Quack! and what it depends on. Every student can both host and attend, so there is one actor.

C4 Level 2: Container

The deployable pieces inside Quack!, their technology, and how they communicate.

Create Event Request Lifecycle

Component responsibilities

React client

Responsibility: Rendering, map interaction, form input, optimistic UI

Explicitly not responsible for: Authorization decisions, domain verification, visibility enforcement

Spring Boot API

Responsibility: OAuth callback handling, domain allowlist, sessions, validation, authorization, business rules, persistence

Explicitly not responsible for: Rendering, tile fetching, geocoding

Postgres

Responsibility: Durable storage, uniqueness constraints, spatial and temporal indexes

Explicitly not responsible for: Business logic in triggers or stored procedures

Mapbox

Responsibility: Map tiles and rendering

Explicitly not responsible for: Storing any of our event data, geocoding (not used)

OAuth provider

Responsibility: Authenticating that the user controls a school email account

Explicitly not responsible for: Authorization. Membership of the school domain is checked by us