oO/README.md

oO

One tip. Right now. Feels like magic.

oO learns who you are from the apps you already use and surfaces one perfectly-timed suggestion — an advice or a todo — on a black page. No feed. No dashboard. One tip.

---

Why

Everyone has too many tasks, too many apps, too much noise. What people actually need is a single, well-chosen nudge at the right moment. oO is that nudge, powered by a recommendation engine that gets smarter the more of your life it sees.

Product principles

1. One thing at a time. The UI is a black page with one tip. That's the product.
2. We don't own your data, we understand it. Connect your apps; we read what we need, when we need it.
3. Magic requires craft. Precision, timing, and restraint matter more than features.
4. Private by default. Tokens are encrypted, models are per-user, deletion is one click.

Prototype scope (Phase 0)

Three pages. That's it.

Page	What it does
Sign in	Google / Apple OAuth. No passwords.
Connect	A list of integrations. Tap "Todoist" → OAuth flow → token stored.
Tip	Black page. One tip. Tap to dismiss / done / snooze.

Under the hood the "pick a tip" call already routes through a recommender service with a pluggable policy — so v0 is literally "random Todoist task" but every other version slots into the same contract.

---

Architecture at a glance

 ┌──────────┐   OAuth   ┌────────────┐
 │  Web /   │──────────▶│   auth     │
 │  Mobile  │           └─────┬──────┘
 │  client  │                 │ JWT
 │          │   REST/GraphQL  ▼
 │          │────────▶┌───────────────┐
 └──────────┘         │   gateway     │──┬──▶ profile
                      └───────┬───────┘  ├──▶ integrations ──▶ Todoist / Google / ...
                              │          └──▶ recommender ──▶ ml/serving (Python)
                              ▼
                      ┌───────────────┐
                      │    events     │ ◀── integrations emit normalized events
                      │  (Kafka/NATS) │ ──▶ ml/pipelines (features, training)
                      └───────────────┘

More detail in docs/architecture/ and decisions in docs/adr/.

Monorepo layout

See CLAUDE.md for the full tree and conventions.

apps/        web, ios, android
services/    gateway, auth, profile, integrations, recommender, events, notifier
packages/    shared-types, sdk-js, ui
ml/          pipelines, features, registry, experiments, serving
infra/       docker, k8s, terraform, ci
docs/        architecture, adr, api

---

Roadmap

Phase 0 — Prototype (M0)

Goal: a single user can sign in, connect Todoist, and see one random Todoist task on a black page.

• Monorepo scaffold, CI skeleton, docker-compose dev env
• auth service with Google OAuth
• integrations/todoist OAuth2 flow + encrypted token vault
• recommender service with RandomPolicy (v0)
• apps/web — three pages (sign-in, connect, tip)
• Deploy to a single VM via docker-compose

Phase 1 — Real signal (M1)

Goal: the tip is picked, not drawn from a hat. Still Todoist-only.

• Event bus (NATS) + ingestion from Todoist sync API
• Feature store skeleton (Feast or homegrown) and the first five features (time-of-day, overdue count, task age, priority, project)
• ml/serving FastAPI scoring endpoint; recommender calls it
• ContextualBanditPolicy v1 (LinUCB) replacing RandomPolicy
• Tip feedback loop: user reactions (done / snooze / dismiss) become rewards

Phase 2 — Multi-source user profile (M2)

Goal: oO knows more than tasks.

• Integrations: Google Calendar, Apple Health (web import), generic webhook
• Unified Profile model (identity, preferences, contexts, consents)
• Timing signals (location, idle, focus windows) via client-side probes
• Advice library (curated tips, not only todos) + mixing policy

Phase 3 — Mobile & notifications (M3)

• iOS app (SwiftUI) with APNs push
• Android app (Compose) with FCM push
• notifier service with quiet-hours + per-channel rate limits
• Rich notifications that deep-link to the tip page

Phase 4 — MLOps at scale (M4)

• Airflow/Prefect orchestrator for batch retrains
• MLflow model registry + shadow deploys
• Online experiments framework: A/B + multi-armed bandits as first-class
• Cohort analysis + cross-user collaborative features (opt-in)
• Model cards, fairness checks, drift monitoring

Phase 5 — Production hardening (M5)

• SOC2-style controls, audit logging, token rotation
• k8s deploy + horizontal autoscaling
• Multi-region failover, PITR backups
• Public integration SDK so third parties can add sources
• Billing + subscription tiers

---

Contributing

This repo is split into independent modules; most tickets belong to exactly one. Pick an issue, check its milestone (= phase), read the service's README.md, ship.

Conventions and per-service guidance live in CLAUDE.md.

License

TBD.