Onboarding Guide

For a new engineer or operator joining the yareta-platform team. Read the System Architecture Document first for the big picture — this guide is about getting productive, not about re-explaining the architecture.

1. Environment Setup

1. Node & package manager: Node 20, pnpm 10.11.1 (pinned via packageManager in package.json). Check .nvmrc for the exact Node version expected.
2. Clone and install: pnpm install.
3. Environment variables: copy .env.example to .env.local (or the relevant .env.<NODE_ENV> file) and fill in values — ask a current team member for development-environment secrets rather than generating your own, since most third-party integrations (Stripe test mode, LLM provider keys, CRM sandbox credentials) need to be shared/coordinated values. See the Infrastructure & Deployment doc for what each category is for.
4. Local D1 database: pnpm migrate:local applies migrations to your local D1 instance. Note: local wrangler dev for the queue worker (via pnpm run queue:start → scripts/queue-dev-start.sh) actually points at the shared development D1 database, not an isolated local one — be careful running destructive tests locally against queue-worker code.
5. Run the app: pnpm dev (Next.js dev server). For testing Cloudflare-specific bindings locally, use pnpm run preview (builds via next-on-pages then runs wrangler pages dev).
6. Run the queue worker locally: pnpm run queue:start (wraps scripts/queue-dev-start.sh, which temporarily swaps in the local queue wrangler.toml and copies .deployment-configs/local/.env.local to .dev.vars).

2. Key Systems and How They Connect

Read in this order for a working mental model:

1. System Architecture Document — what Yareta is, the two deployable units, how chat-sparkle-vision and yareta-file-processor relate.
2. Technical Design Document — the dual job-dispatch system, the LLM abstraction, billing, and the report-generation pipelines you’ll most likely touch first.
3. Database Documentation — the schema, and critically, the migration-numbering-collision gotcha (§3) before you generate your first migration.
4. API Documentation — the three separate API surfaces (GraphQL, Developer REST, Zapier), and the fact that the GraphQL endpoint is /api, not /api/graphql (a mistake nearly everyone makes once).

3. First Tasks — Where to Look

If you’re working on…	Start in…
A new GraphQL query/mutation	src/graphql/<domain>/ — follow the existing queries.ts/mutations.ts/services.ts/graphqlTypes.ts convention for that domain
A new background job	src/jobs/runners/ (the newer pattern — see Technical Design §1) rather than adding to the older src/queue/workers/ map, unless extending an existing worker family
A schema change	src/db/schema/<domain>.ts, then pnpm drizzle:generate — check the current highest migration number first to avoid a numbering collision
An AI prompt change	The prompt lives in two places: code (src/prompts/*.ts or wherever the relevant service builds it) and the system_prompts DB table. Changing the code default does not change live behavior until synced to the DB — see the Admin Guide
A new external integration	Look at an existing one with a similar shape first (Airtable/HubSpot for CRM-style bidirectional sync, Fireflies/Recall.ai for transcript ingestion, DocuSign for outbound-only) — the Integration Documentation catalogs the existing patterns
A frontend-facing API change that Lovable (chat-sparkle-vision) depends on	Confirm with the team before changing shape/behavior of any GraphQL field Lovable’s Supabase BFF calls — there’s no automated cross-repo contract test

4. Testing

Run pnpm test (Vitest) before opening a PR — CI does not run tests automatically (pr-checks.yml only runs format/lint/typecheck), so this is on you. Existing tests live under src/__tests__/, concentrated on API routes, integrations, and the investor-team-summary pipeline — if you’re working in one of those areas, look at the existing test file for the pattern (mocked D1/Drizzle, mocked NextAuth session, testGraphQLQuery/testGraphQLMutation helpers in src/__tests__/utils/).

5. How the Team Works (Process)

• Every PR needs a linked Notion task — notion-pr-sync.yml fails the check on any non-draft PR without one (a notion.so URL or a Notion-Page-ID: <uuid> line in the description). Link it before marking a PR ready for review.
• PR events (open, new commits, merge, close) automatically post status comments back to the linked Notion page — you don’t need to manually update Notion for basic PR lifecycle events.
• PRs merge to development first; development is later merged/pushed to production to release (see the Deployment / Release Runbook).

6. Who to Ask

This document can’t maintain an accurate team directory reliably — check the team’s current internal roster (Notion, Slack) for who owns which area. As a starting orientation, the areas most likely to need a specific person’s context (rather than being self-service from these docs) are: the LLM prompt library and its DB-sync process, the billing/credit reconciliation logic, and anything touching the chat-sparkle-vision (Lovable) contract, since a change on either side needs coordination that isn’t enforced by any automated check.

7. Common First-Week Gotchas

• The GraphQL endpoint is /api, not /api/graphql.
• Editing a prompt in code doesn’t change production behavior until it’s synced to the DB.
• Migration numbers collide in this repo — check before you generate a new one.
• Local queue-worker dev talks to the real development D1 database, not an isolated one.
• SKIP_APOLLO_AUTH=TRUE disables all GraphQL auth — never set it outside strictly local development.

---

Related documents: System Architecture · Maintenance Guide · Deployment / Release Runbook