Architecture.

The shape of the system

One product, a handful of moving parts. Members and admins use a single web app; it talks to a backend that runs mostly as Cloud Functions, with a legacy Go service still serving some integrations. Everything reads and writes the same datastore, and it all runs on GCP.

Simplified on purpose. Queues, search, storage, and a long tail of providers sit around this core — see Integrations for the provider map.

Key concepts

A few ideas hold across the whole system. Internalize these and most of the codebase will feel familiar.

• One monorepo. The web app, both backends, shared packages, and the infrastructure-as-code all live in perkupapp/perkup-app. One checkout, one set of tooling.
• One web app. Admins and members use the same SPA, gated by role — not two separate frontends.
• Functions-first backend. New backend code is Cloud Functions in TypeScript. The Go service is in maintenance mode; we migrate toward functions, not away.
• Contracts come first. Service and data shapes are defined as protobuf and generated into both Go and TypeScript, so the wire format is shared rather than hand-kept in sync. The generated code is checked in and CI fails on drift.
• Firestore is the datastore. Document-oriented, shared by both backends. There is no separate relational database in the core path.
• Everything runs on GCP, declared in code. Buckets, load balancing, queues, and pub/sub are defined in the pulumi/ stacks rather than clicked together in a console.

Where things live

When you are looking for the right place to put something, this is the orientation table. It is a starting point, not a rulebook — the directory's own AGENTS.md has the detail.