Repository navigation
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.
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.
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) |
IMailer |
provider-swappable |
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.
- 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.
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
- 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).
- SuperAdmin — internal admin/governance panel, separate repo, its own ADR log. Auth-only persistence (SuperTokens), no dedicated database.
- Getting Started — run it locally.
- ADR Index — why it is built this way.
- Data Layer · Auth & Identity · Payments · Realtime · ActivityPub Federation · FHIR · Multi-Tenancy & RBAC · Shared Packages.
Home · Architecture · ADRs · Plans · Roadmap · Contributing · Main repo · DeepWiki · Discord
Yosemite Crew is a product of DuneXploration UG (haftungsbeschränkt). This wiki mirrors the repository; where a page and the repo disagree, the repo wins. See the Wiki Style Guide.
Product & Domain
Architecture
Applications
- Backend — Overview
- Frontend / PIMS Web — Overview
- Mobile — Overview
- Desktop PIMS Shell
- Developer Portal
- SuperAdmin
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Meta
Canonical code & docs: main repo · Auto-generated companion: DeepWiki