Sarthi is an AI coaching companion that helps people follow through on commitments with supportive autonomy: plans and nudges stay explainable, controllable, and aligned with what the user actually wants to do.
- Agency first: autonomous actions are explainable, reviewable, and user-controllable.
- Calm reliability: reminders, plans, and interventions behave predictably (Android-first release, then iOS).
- Contract-first: backend APIs and event schemas are defined before UI work expands.
- Evidence-driven: product changes lean on telemetry and user outcomes, not feature count alone.
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ Mobile (Expo / RN + TS) │◀─────▶│ Backend (FastAPI + Python) │
│ Android first, then iOS │ │ REST / JSON, Postgres │
└─────────────────────────────┘ └──────────────┬──────────────┘
│
┌──────────────┴──────────────┐
│ Jobs, LLM services, etc. │
└─────────────────────────────┘
SarthiAI/
├── backend/ # FastAPI service (scaffold when you start the API)
├── mobile/ # Expo + React Native app
├── docs/ # Product scope, ADRs, analytics taxonomy, API contracts
├── README.md
└── .gitignore
| Artifact | Path |
|---|---|
| Android v1 scope (FROZEN) | docs/product/v1-scope.md |
| Phase 2 readiness review | docs/product/phase2-readiness-review.md |
| Quality gates (Phase 2 evidence) | docs/engineering/quality-gates-v1.md |
| Decision record policy (in-repo) | docs/governance/decision-record-policy.md |
| Architecture Decision Records | docs/adr/README.md |
| Public HTTP API (OpenAPI 3.1) | docs/contracts/openapi.yaml |
| Analytics taxonomy (FROZEN) | docs/analytics/taxonomy-v1.md |
Lint OpenAPI (fast, pinned CLI): from repo root, cd tooling/openapi && npm ci && npm run lint (see docs/contracts/README.md). Prefer this over repeated npx @redocly/cli, which downloads on each invocation and is easy to mistake for a hung terminal.
Decisions and rationale live in docs/adr/. Summary:
| Layer | Choice |
|---|---|
| Mobile | React Native, Expo (EAS), TypeScript (ADR 0009) |
| Navigation / state (target) | React Navigation; TanStack Query; Zustand; React Hook Form + Zod (per program spec; wire in Phase 2) |
| API | FastAPI, Pydantic; public contract in docs/contracts/openapi.yaml (/v1) |
| Auth | JWT access + refresh (ADR 0006) |
| Data | PostgreSQL, SQLAlchemy, Alembic (ADR 0010) |
| Jobs | Redis + RQ (ADR 0001); idempotency at HTTP boundary |
| Product analytics | PostHog (ADR 0002); taxonomy |
| Error monitoring | Sentry (ADR 0007) |
| Tracing / logs | OpenTelemetry + structured JSON logs, minimal bootstrap (ADR 0008) |
| CI/CD | GitHub Actions (ADR 0004) |
| Mobile E2E smoke | Maestro (ADR 0003) |
| Pinning | uv + uv.lock (Python), npm + package-lock.json (ADR 0005) |
Python 3.11+ and Node Active LTS are required; pin CI images when workflows land.
- Node.js (LTS) and npm — for Expo / React Native.
- Python 3.11+ — for the FastAPI backend when added.
- PostgreSQL — for production-like local development once the backend exists.