chore: scaffold oO monorepo with architecture, roadmap, and module stubs
This commit is contained in:
126
README.md
Normal file
126
README.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user