# irc.now Platform Roadmap

High-level vision and phase overview. Detailed implementation plans are written
per-phase as work begins.

## Vision

irc.now is a hosted IRC services platform. Sign up, get a bouncer. Upgrade to
pro, get a dedicated bouncer with a custom hostname. Host your own IRC network.
Run bots with Lua scripts. Share images and pastes. Everything connected
through one account with SSO.

## Phases

### Phase 1: Foundation

Get the core platform running: users can sign up, create a bouncer, and pay.

| Item | Description | Status |
|------|-------------|--------|
| Rust workspace | Monorepo with shared `common` crate | done |
| GitOps manifests | CNPG clusters, namespace, RBAC, secrets | done |
| Keycloak | Dedicated instance at `auth.irc.now`, `irc-now` realm, OIDC clients | done |
| soju-operator | Existing 14-task plan, manages SojuBouncer CRDs | done |
| Account portal | `my.irc.now` -- Axum, OIDC auth, bouncer CRUD, Stripe billing | done |
| Landing page | `irc.now` -- deploy existing static site, link to portal | done |

**Detailed plan:** `docs/plans/2026-03-03-irc-now-phase1-plan.md`

---

### Phase 1.5: Fill the Gaps

Phase 1 code is deployed but most handlers are stubs. This phase makes
everything the landing page promises actually work.

| Item | Description | Status |
|------|-------------|--------|
| Auth guard | `FromRequestParts` extractor, redirect to login if unauthenticated | planned |
| Users table | DB table + upsert on OIDC callback, plan/stripe_customer_id in session | planned |
| Dashboard/bouncers | Wire to kube API, real plan from session, bouncer CRUD via SojuBouncer CRs | planned |
| Stripe checkout | Checkout session, billing page, customer portal, webhook handler | planned |
| Content pages | docs, clients, faq, what-is-irc static pages, extract CSS | planned |
| status.irc.now | Upptime on GitHub Pages, monitors all endpoints | planned |
| Decommission ZNC | Remove znc.josie.lol deployment and DNS | planned |

**Detailed plan:** `docs/plans/2026-03-04-irc-now-phase1.5-plan.md`

---

### Phase 2: Observability

Instrument everything before deploying more services. If it's not monitored,
it's not production.

| Item | Description |
|------|-------------|
| Prometheus | OCP built-in or deploy dedicated instance for irc-now metrics |
| Alertmanager | Alert rules: service down, reconciliation failures, cert expiry, DB connection loss |
| Grafana | Dashboards for platform health, operator status, per-service request rates |
| Metrics endpoints | `/metrics` on all Axum services (prometheus-client crate), operator reconciliation metrics |
| Alert delivery | Email initially, IRC ops channel via bot webhook relay once bots are built |

**Key metrics:**
- Axum: request rate, latency p50/p95/p99, error rate per route
- Operators: reconciliation loop duration, queue depth, error count
- CNPG: connection pool usage, replication lag, storage usage
- Keycloak: login success/failure rate, active sessions

---

### Phase 3: Supporting Services

The tools that make the platform useful beyond just a bouncer.

| Item | Description |
|------|-------------|
| chat.irc.now | Gamja web client, themed with design system CSS, connects via user's soju bouncer |
| txt.irc.now | Pastebin -- Axum, PostgreSQL storage, anonymous + authenticated, syntax highlighting, short URLs. Free: 5 pastes, 24h expiry. Pro: unlimited, no expiry |
| irc.pics | Image host -- Axum, S3 storage, authenticated upload, thumbnail generation, short URLs. Free: 50MB. Pro: 1GB |
| Log search | Full-text search across scrollback history. Add-on: $2/mo |

**Dependencies:** Phase 1 (auth, DB infrastructure) must be complete. Phase 2
(monitoring) should be in place so new services are instrumented from day one.

---

### Phase 4: Network Hosting

Let users run their own IRC networks. Starter: $12/mo (50 users, 1 server, 3 bots).
Growth: $24/mo (200 users, 3 servers, 10 bots).

| Item | Description |
|------|-------------|
| ergo-operator | Same kube.rs pattern as soju-operator, manages ErgoNetwork CRDs |
| ErgoNetwork CRD | Reconciles into Deployment (ergo), ConfigMap, Service, Route, Certificate, per-tenant DB |
| Portal integration | Network management tab in account portal -- create/configure/delete ergo instances |
| DNS | Wildcard `*.irc.now` or per-tenant subdomain creation |

**Architecture note:** ergo is MIT licensed, so if you need to patch it for
multi-tenant features (custom MOTD, connection limits, telemetry hooks) there
are no license constraints.

---

### Phase 5: Analytics

Understand how the platform is used. Inform product decisions.

| Item | Description |
|------|-------------|
| Event tracking | Record signups, logins, bouncer creates, plan upgrades, churn events in `accounts` DB |
| Business dashboards | Grafana dashboards: MRR, conversion rate, active users, retention cohorts |
| Per-user stats | Surface in account portal: bouncer uptime, networks connected, messages relayed, storage used |
| Stripe analytics | Revenue, failed payments, subscription lifecycle |

**Privacy note:** Analytics are first-party only. No third-party tracking.
Aggregate metrics in Grafana, per-user stats visible only to the user and ops.

---

### Phase 6: Bots

Managed IRC bot runtime. The differentiating feature. Standalone: $2/mo per bot.
Network hosting plans include bot quotas.

| Item | Description | Status |
|------|-------------|--------|
| Bot runner | Rust service (crates/bot), manages bot instances in-process, one mlua (Lua 5.4) VM per bot | done |
| IRC connectivity | Bots connect through user's soju bouncer to any network, SASL PLAIN auth | done |
| Built-in scripts | Template Lua scripts: linkbot (URL titles), rsswatch (RSS feeds), sed (s/typo/fix), watchdog (moderation) | done |
| Lua sandbox | Event-driven API: on_message/on_join/on_part/on_kick/on_nick/on_notice, 8MB memory + 1M instruction limit | done |
| Lua API | irc.send/join/part/nick, kv.get/set/delete/list, log.info/warn/error, http.get (10/min), timer.after/every | done |
| Portal UI | Bot CRUD, script editor with API reference, live log viewer (WebSocket), KV browser | done |
| Reconnection | Exponential backoff (1s-60s), startup jitter (0-30s) for enabled bots | done |
| Plan enforcement | Free: 1 bot, Pro: 5 bots | done |
| Infra provisioning | CNPG bot-db, Keycloak client, BuildConfig, WebService CR, ArgoCD entry | planned |

**Runtime model:** All bots run in a single Deployment, multiplexed on async
IRC connections via tokio. Scales horizontally by sharding users across
replicas. No per-bot CRD -- configs live in the database. This keeps it simple
and avoids operator overhead for application-level multiplexing.

**Sandbox boundaries:** No `os`, `io`, `require`, `loadfile`, `debug`. Scripts can only
call the IRC API and KV store. `http_get` is rate-limited (10 req/min per bot). Each
Lua VM has an 8MB memory ceiling and 1M instruction count limit per event dispatch.

**Detailed plan:** `docs/plans/2026-03-05-bot-service-plan.md`

---

## Cross-Cutting Concerns

### Auth
All services authenticate via Keycloak OIDC. The `common` crate provides Axum
middleware that validates tokens and extracts `UserClaims` (sub, email, plan,
stripe_customer_id). Gamja authenticates through a proxy that resolves the
user's bouncer endpoint.

### Design System
All user-facing HTML uses the irc.now design system: Newsreader/Outfit/JetBrains
Mono fonts, green-on-dark palette, IRC-native component patterns. Shared via
static CSS files from `design/tokens/` and `design/components/`.

### Deployment
Everything runs on OCP. Container images built via `oc builds` (multi-stage
Rust builds to UBI9-minimal). OCP Routes handle TLS termination per subdomain.
cert-manager issues certificates via LetsEncrypt. CNPG manages PostgreSQL.

### Database Strategy
Single CNPG cluster. Separate databases per service (keycloak, accounts, paste,
pics). Per-tenant databases for operators (soju_*, ergo_*). Operators hold
master credentials and create scoped roles per tenant.