Skip to content

Developer Portal

Ankit Upadhyay edited this page Jul 9, 2026 · 1 revision

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.

Documentation site (Docusaurus + OpenAPI)

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.

The MCP server (@yosemite-crew/mcp-server)

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/mcp in the main repo, which is a packaged Claude Code plugin bundle (yosemite-crew.plugin with skills/hooks), a different artifact.

Starter CLI (create-yosemite-app)

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 Developer Data API (contract; backend in unmerged PRs)

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 }"]
Loading

(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_… or X-API-Key; SHA-256 hashed key lookup; unknown/revoked/expired all return the same 401. Middleware sets req.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 (+ reserved config:read, config:draft:write for 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).

The AI editing agent

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-*.

Client-side

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).

Related

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