Repository navigation
Developer Portal
Yosemite Crew is designed as infrastructure — external developers build on its APIs. The developer platform spans docs, an MCP server, a starter CLI, and a read-only Data API. Decisions: ADR-0004 (tenant residency) and ADR-0005 (AI editing agent).
Status note: several developer-platform capabilities are specified and partly built in unmerged PRs, not yet on
main. Where that's the case it's called out below so this page doesn't over-claim shipped code.
apps/dev-docs — a Docusaurus site (title "Yosemite Crew Developer Docs", baseUrl /dev-docs/, local search). Content under docs/ includes overview.md, openapi.md, per-app pages, and an autogenerated apps/backend/routers/* reference (~40 router pages). The OpenAPI reference is served as static assets (static/openapi.yaml + static/openapi-ui.html), surfaced via docs/openapi.md.
packages/mcp-server — a stdio MCP server (binary yc-mcp) that gives AI agents read-only access to a YC org via the Developer Data API. src/index.ts bootstraps McpServer({ name: 'yosemite-crew' }); src/client.ts requires a YC_API_KEY (yc_live_…/yc_test_…, sent as Authorization: Bearer). Tools (each pinned to a scope) hit /v1/developer/*:
| Tool | Endpoint | Scope |
|---|---|---|
list_appointments / get_appointment
|
/v1/developer/appointments |
appointments:read |
list_patients / get_patient
|
/v1/developer/patients |
patients:read |
list_encounters / get_encounter
|
/v1/developer/encounters |
encounters:read |
list_invoices / get_invoice
|
/v1/developer/invoices |
invoices:read |
get_organization |
/v1/developer/organization |
organization:read |
get_usage |
/v1/developer/usage |
(none; doesn't consume quota) |
Not to be confused with
apps/mcpin the main repo, which is a packaged Claude Code plugin bundle (yosemite-crew.pluginwith skills/hooks), a different artifact.
packages/create-yosemite-app — a non-interactive scaffolder (npx create-yosemite-app my-integration). src/scaffold.ts copies the api-starter template and substitutes the project name; the template ships a dependency-free, fetch-based typed client for the read-only Data API v1 (Bearer auth, { data, pagination } envelope, { message, code } errors, 429 handling) plus a .env.example (YC_API_KEY, YC_API_BASE_URL) and README documenting scopes and the /developers/api-keys issuance flow.
The v1 Data API is the contract the MCP server and create-yosemite-app target.
flowchart LR
APP["Developer app / MCP server"] -->|"Bearer yc_live_..."| MW["authorizeApiKey<br/>(SHA-256 key lookup)"]
MW --> KEY["DeveloperApiKey<br/>organisationId + scopes + env"]
KEY --> SCOPE["requireScope(...)"]
SCOPE --> METER["DeveloperApiUsage<br/>meter + rate limit"]
METER --> Q["org-scoped query<br/>WHERE organisationId = key.org"]
Q --> RESP["{ data, pagination }"]
(Diagram shows the target contract; the middleware/models live in unmerged PRs, not yet on main.)
The backend implementation (developer-data.router.ts, middlewares/api-key-auth.ts with authorizeApiKey + requireScope, and the DeveloperApiKey / DeveloperApiUsage models/services) is specified in plans/ADRs and unmerged/closed PRs (#1696, #1726), not present on main — describe it as the target contract, not shipped code. Key contract points (docs/plans/developer-portal-data-api.md):
-
Auth:
Authorization: Bearer yc_live_…orX-API-Key; SHA-256 hashed key lookup; unknown/revoked/expired all return the same401. Middleware setsreq.apiKey({ id, organisationId, scopes, environment }). -
Org scoping is absolute — every query is filtered by the key's
organisationId(row-level, shared schema; the schema-per-tenant machinery is orthogonal — ADR-0004). -
Scopes (v1):
appointments:read,patients:read,encounters:read,invoices:read,organization:read(+ reservedconfig:read,config:draft:writefor the AI agent). -
Metering: free tier hard-stops at 1,000 calls/month (
429 quota_exceeded), pro is metered to Stripe, plus a per-key sliding-window rate limit. Cursor pagination{ data, pagination: { nextCursor, hasMore, limit } }. -
Environments:
live|test(test keys read-only, excluded from Stripe billing but still counted toward the free cap).
Phase 2 puts an in-browser AI agent in /developers that edits PIMS config (Forms/Templates/ObservationTool) through an MCP toolset. Its security model — config-scoped, draft-only, human-promoted, assume-the-model-is-compromised — is ADR-0005. Related designs (delegated OAuth, FHIR API, webhooks, website builder, Tier-2 GitHub App, plugin registry, marketplace monetization) live in docs/plans/developer-portal-*.
The web app exposes developer surfaces under (app)/developers/(portal) and a public (public)/developers/signin (Frontend: Public and Marketing Pages), gated by the DevRouteGuard (Frontend: Auth and Session).
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