# 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/`](docs/architecture/) and decisions in [`docs/adr/`](docs/adr/).

## Monorepo layout

See [`CLAUDE.md`](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`](CLAUDE.md).

## License

TBD.