A voice-first personal assistant that turns how you talk about your day into structured data you can query later.
Cadence is built around a simple idea: people don’t naturally speak in database rows. They say things like “Hour at the gym, felt pretty good”—messy, contextual, and time-relative. This project explores turning that kind of input into normalized activities, sentiment, and timelines, then connecting those events over time so you can ask richer questions than a typical journaling or habit app allows.
It’s implemented as a small monorepo: a mobile client, a Python API for the agent and voice pipeline, and Supabase (Postgres + pgvector) as the relational and semantic backbone, with Neo4j intended for correlation-style queries across habits and mood. The architecture is deliberately split so API keys for LLMs and speech stay on the server—nothing sensitive ships in the app binary.
- Voice-first UX with streaming speech-to-text relayed through a backend (Deepgram), not embedded keys in the client.
- Agent-style orchestration (LangGraph + Groq) with strict structured outputs (Pydantic) so free-form speech becomes reliable entities and timestamps—including temporal grounding (e.g. “this morning” resolved against the user’s timezone).
- Hybrid data model: relational + vector search (pgvector) for entries, and a graph layer (Neo4j) for relationships like activity → mood → follow-on behavior—enabling questions that are awkward in flat tables alone.
- Production-shaped API: FastAPI, Docker, Fly.io-oriented deploy, CORS and secrets handled as you’d expect in a real service.
| Path | Role |
|---|---|
apps/mobile |
Expo (React Native) app—onboarding, Supabase auth, client shell. |
services/api |
FastAPI service—health/docs today; agent, STT relay, and graph routes are wired incrementally. |
supabase/migrations |
SQL migrations for Postgres, pgvector, and RLS-friendly schemas. |
Product vision, pipeline details, and phased build plan live in .docs/App Design and features.md and .docs/Implementation Plan.md (including a project status section that tracks what’s landed in the repo).
The repo reflects an active build: authentication and Supabase connectivity are in place on mobile; the API exposes OpenAPI docs and connection checks for external services; Neo4j and full agent routes are planned / partially integrated per the implementation plan—not a finished consumer product yet. That’s by design: the README is meant to show how the system is meant to work, not to oversell completeness.
Prerequisites: Node.js LTS, Python 3.12+, and optionally Docker / Fly CLI / Supabase CLI for deploy and migrations.
Mobile (Expo)
cd apps\mobile
npm install
copy .env.example .env
# Set EXPO_PUBLIC_SUPABASE_URL and EXPO_PUBLIC_SUPABASE_ANON_KEY
npm run startAPI (FastAPI)
cd services\api
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# Configure API keys and URLs as in services/api/.env.example
uvicorn app.main:app --reload --host 127.0.0.1 --port 8080Open http://127.0.0.1:8080/docs. Optional: python scripts\check_connections.py smoke-tests Groq / Deepgram / Neo4j when configured.
Database: Apply supabase/migrations via the Supabase SQL Editor or CLI (supabase db push) after creating a project—see the Implementation Plan for schema intent.
Secrets: Never commit .env files. Only .env.example files belong in Git. For Fly.io, use fly secrets set from services/api as documented in .docs and services/api deploy config.