Skip to main content

Architecture overview

Gelpy connects general-services professionals with people who need help, with safety and trust. Phase 1 builds the application base: accounts, sign-in, app navigation, and notifications. Marketplace features come in Phase 2.

Status

Phase 1 is in development. This page describes the planned design. A capability is documented as available only after it reaches production.

System context​

Components​

ComponentRoleTechnology
AppThe product people use, on Android and in the browserExpo, React Native, TypeScript, Expo Router, TanStack Query
WebsitePublic pages in Spanish and EnglishNuxt (static generation), TypeScript, Tailwind CSS
Admin consoleInternal administration for Gelpy operatorsNext.js, TypeScript, Tailwind CSS
APIBusiness logic, authentication, and data accessNode.js, Express, TypeScript, Zod, Prisma client
DatabaseSystem of recordManaged PostgreSQL with SQL migrations
Design systemShared design tokens and assetsDesign tokens, SVG assets
Engineering docsThis siteDocusaurus on GitHub Pages

Runtime platform​

  • The API runs as a container on Cloudflare Containers, behind a Cloudflare Worker that receives every request.
  • The app, the website, and the admin console are served as static assets from Cloudflare.
  • The database is managed PostgreSQL, reached through Cloudflare Hyperdrive.
  • There is no self-managed server.

Environments​

There are two environments: test and production. Each one has its own Worker, database, secrets, OAuth clients, and passkey configuration. Test never holds production personal data.

Build and release flow​

  • Work starts on a branch and merges into staging after the quality gates pass. staging deploys to the test environment.
  • A release pull request promotes staging to main, which deploys to production. It needs explicit owner approval.
  • Production runs the same API image that was tested on staging. The image is not rebuilt.
  • Releases follow Semantic Versioning. Each release gets a Git tag and release notes from the changelog.

Data model ownership​

SQL migrations are the only source of the database schema. The API generates its database client from that schema and never changes the schema itself. Migrations run before the API deploys and follow the expand-and-contract pattern, so old and new API versions work during a release.