127 lines
5.4 KiB
Markdown
127 lines
5.4 KiB
Markdown
# 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.
|