Ech0 Dojo — Memory Garden (Voice Journaling)

Ech0 Dojo (spelled with a zero) is a voice-first journaling and memory system. Record a thought, upload it, and return later to hear and reflect on it. The project pairs a React client with an Express + Apollo GraphQL API and an async transcription pipeline.

Status: MVP in active development. External integrations (OpenAI, S3, Supabase) are optional and stubbed for CI.

Table of Contents

• Overview
• Architecture
• Quickstart (Local Development)
• Environment Variables
• Scripts
• Testing & Deterministic CI
• Repository Structure
• Roadmap
• Documentation

Overview

Ech0 Dojo helps you:

• Record voice memories.
• Upload and transcribe audio asynchronously.
• Review and edit transcripts before saving.
• Browse entries in a calm, ambient UI.

The system favors durable memory (entries persist immediately) and gentle AI (reflection and augmentation, not replacement).

Architecture

Frontend

• React (Vite)
• Apollo Client
• TailwindCSS
• Audio recording + playback UI

Backend

• Node.js + Express
• Apollo Server (GraphQL)
• MongoDB (Mongoose)
• Redis (queue + worker coordination)

AI / Observability (optional)

• Whisper transcription (Scribe worker)
• OpenAI for reflection/summarization (stubbed in CI)
• Langfuse tracing (no-op client in tests)

Storage

• S3-compatible storage for audio (production)
• Local file storage for demo/demo-like environments

Quickstart (Local Development)

1. Install dependencies

   pnpm install

   Note: Codex users should be on Codex 0.98.0 or newer to use gpt-5.3-codex (breaking update as of 2026-02-07).

2. Create env files

   cp server/.env.example server/.env
   cp client/.env.example client/.env

3. Start the app (client + server)

   pnpm dev

4. Optional: start local Redis + MongoDB with Docker

   pnpm db:up

Environment Variables

Minimal local setup (client):

• VITE_API_BASE_URL=http://localhost:4000

Server config highlights:

• SUPABASE_JWT_SECRET (required for auth validation in production)
• OPENAI_API_KEY (optional; stubbed in CI)
• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_BUCKET_NAME (optional; local storage is used in demo/test)
• REDIS_URL (required only when running worker queues)

See docs/ENV_SETUP.md for a full list.

Scripts

From repo root:

• pnpm dev — run client + server concurrently
• pnpm build — build client (server has no build step)
• pnpm lint / pnpm lint:ci — lint all workspaces
• pnpm test / pnpm test:ci — run tests (CI uses coverage)
• pnpm graphql:ci — validate client GraphQL operations
• pnpm db:up / pnpm db:down — local services via Docker

Workspace-specific:

• pnpm --filter client dev
• pnpm --filter server start
• pnpm --filter server worker

Testing & Deterministic CI

CI is deterministic by default:

• Outbound network requests are blocked in server tests.
• Known external calls (e.g., OpenAI transcription) are served from fixtures.
• Tests pass without secrets.

Recommended local gate:

pnpm lint:ci
pnpm test:ci

Repository Structure

client/                 # React app (Vite)
server/                 # Express + Apollo API
server/src/workers/     # Queue workers (scribe)
server/routes/          # REST endpoints (upload + reflect)
server/graphql/         # Schema + resolvers
server/models/          # Mongoose models
scripts/                # CI + automation utilities
reports/                # CI artifacts + SYSTEM_MAP
docs/                   # Product + technical documentation

Roadmap

Now

• Deterministic CI and fixtures for external integrations
• Record → upload → transcript → playback reliability
• Clear UI states and retry-safe flows

Next

• Search, tagging, and richer filtering
• Expanded reflection tooling
• Vibe rating (spec-first, privacy-conscious)

Documentation

• docs/AGENTS.md — contributor protocols
• docs/ENV_SETUP.md — environment setup
• docs/contracts/storage-contract.md — audio storage contract (regression guard)
• docs/drafts/README_SEED.md — seed source