Skip to content

Architecture Overview

Ankit Upadhyay edited this page Aug 25, 2026 · 4 revisions

Architecture Overview

Yosemite Crew is a pnpm + Turborepo monorepo. This page is the map; for anything that changes with the code (exact configs, commands, decisions), it links to the source of truth in the main repo or the deeper wiki pages rather than duplicating it here.

For code-level, ask-anything answers, the auto-generated DeepWiki indexes the current source. This page and its children give the curated, decision-level view.

What we are building

An open-source, FHIR-oriented, multi-species veterinary Practice Management System designed as infrastructure: the developer portal is a first-class product, and integrations (labs, payments, AI, email) plug in behind stable interfaces rather than being hard-wired. Two properties shape most of the interesting engineering decisions:

  • Multi-tenant clinic data with financial and clinical records — invoices, payments, SOAP notes, appointments, controlled-substance logs all need relational integrity and org-scoped access control, not just document storage. See Multi-Tenancy and RBAC.
  • Interoperability-first — clinical entities model against FHIR R4 so data can interoperate with external lab/EHR systems rather than being locked into a proprietary schema. See FHIR and Interoperability.

The "agnostic everything" principle

A recurring design rule: external vendors sit behind an interface, so no single vendor is load-bearing.

Concern Boundary Implementations
Auth provider-neutral guard (ADR-0003) SuperTokens (current, self-hosted, via @yosemite-crew/auth); Cognito + Firebase (legacy, grace-window token verifiers only)
Payments PaymentProviderPort (ADR-0002) Stripe (direct charges); CareCredit / Scratchpay (financing)
Labs LabOrderAdapter IDEXX (live), Antech / in-house (planned)
AI IAIProvider Anthropic, OpenAI (bring-your-own key)
Email IMailer provider-swappable

Monorepo layout

apps/
  backend/       API server - the source of truth for all business logic (Express, Prisma)
  frontend/      Next.js web app (PIMS - Practice Management System) + public/marketing site
  mobileAppYC/   React Native mobile app (pet owners)
  desktop/       Electron PIMS desktop shell
  dev-docs/      Docusaurus developer portal (API reference / OpenAPI)
packages/
  database/      Prisma schema, migrations, Postgres client, tenant provisioning
  fhir/          FHIR R4 converters and compatibility helpers
  fhirtypes/     FHIR type definitions
  auth/          Shared auth helpers
  types/         Shared TypeScript types
  lib/           Shared errors and reusable utilities
  design-tokens/ Semantic design tokens - declared but currently unbuilt and unconsumed;
                 the live web tokens are CSS custom properties in apps/frontend/src/app/globals.css

Full build tooling and workspace commands: CONTRIBUTING.md and monorepo-ops. Per-app deep dives: Backend · Frontend · Mobile · Desktop · Developer Portal.

Technology at a glance

  • Language: TypeScript everywhere. Monorepo: pnpm workspaces + Turborepo.
  • Backend: Node.js + Express, layered Router → Controller → Service → Model, Zod validation, Winston logging, BullMQ jobs. See Backend Overview.
  • Database: PostgreSQL via Prisma (Supabase-hosted managed Postgres; accessed through the connection string, no Supabase SDK). The legacy MongoDB store was retired — its migration scaffold was removed in PR #1819 (merged 2026-07-18). See Data Layer and ADR-0001.
  • Web: Next.js + React, Zustand for state. Mobile: React Native, Redux Toolkit.
  • Realtime: chat via Stream Chat, push via FCM, time-based automation via BullMQ over Redis. A Redis Pub/Sub + Socket.IO org-event bus for browser live-sync is a proposed design documented in docs/guide/realtime-backend.md (which also carries the shared event contract) - not current behavior. See Realtime and Notifications.
  • Federation: clinic-to-clinic networking over ActivityPub - backend protocol services, HTTP-signature crypto, a frontend network directory at /network, and federation tables with row-level security. See ActivityPub Federation.
  • Infra: AWS; Redis for cache and queues.

Request flow (simplified)

flowchart LR
    subgraph Clients
        FE[apps/frontend<br/>Next.js web PIMS]
        MOB[apps/mobileAppYC<br/>React Native]
        DESK[apps/desktop<br/>Electron]
        DEV[Third-party apps<br/>Developer API]
    end

    subgraph Backend[apps/backend]
        API[Express API<br/>Router-Controller-Service]
        JOBS[BullMQ workers]
    end

    subgraph Data
        PG[(Postgres<br/>via Prisma)]
        REDIS[(Redis)]
    end

    STRIPE[Stripe Connect<br/>clinic accounts]
    STREAM[Stream Chat]
    FCM[FCM push]
    FED[Remote clinic instances<br/>ActivityPub federation]

    FE --> API
    MOB --> API
    DESK --> API
    DEV --> API
    API --> PG
    API --> STRIPE
    API --> STREAM
    STREAM --> FE
    STREAM --> MOB
    API --> FCM --> MOB
    API --> JOBS --> REDIS
    API <--> FED
Loading

How the pieces connect

  • The backend is the single source of business logic. Web, mobile, desktop, and third-party developer apps are all clients of the same API. Clinical and financial rules live server-side, never in a client.
  • Postgres/Prisma is the sole system of record. The incremental migration from MongoDB completed, and its dual-write/read-switch scaffold was removed in PR #1819 (merged 2026-07-18) (ADR-0001; follow-ups tracked in #1818).
  • Chat runs on Stream Chat, push on FCM, and background automation on BullMQ (Redis-backed). A Redis/Socket.IO org-event bus for browser live-sync is designed but not yet wired (Realtime).
  • Clinics federate with each other over ActivityPub. Verified clinics discover peers, follow each other, and exchange referrals across instances - a backend protocol subsystem (activitypub.service.ts, activitypub-crypto.service.ts, activitypub.router.ts), a frontend network directory (features/federation, /network), and federation tables with row-level security (ActivityPub Federation).
  • Money never touches the platform — clinics are the merchant of record on their own Stripe accounts (ADR-0002).

Related repositories

  • SuperAdmin — internal admin/governance panel, separate repo, its own ADR log. Auth-only persistence (SuperTokens), no dedicated database.

Where to go next

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally