docs(03): capture phase context
This commit is contained in:
105
.planning/phases/03-operator-experience/03-CONTEXT.md
Normal file
105
.planning/phases/03-operator-experience/03-CONTEXT.md
Normal file
@@ -0,0 +1,105 @@
|
|||||||
|
# Phase 3: Operator Experience - Context
|
||||||
|
|
||||||
|
**Gathered:** 2026-03-24
|
||||||
|
**Status:** Ready for planning
|
||||||
|
|
||||||
|
<domain>
|
||||||
|
## Phase Boundary
|
||||||
|
|
||||||
|
Operators can connect messaging channels (Slack via OAuth, WhatsApp via guided setup), onboard through a guided wizard, manage subscriptions via Stripe (per-agent monthly pricing with 14-day trial), provide their own LLM API keys, and view agent cost/usage metrics — all through the existing portal UI. Phase 3 builds on the portal foundation from Phase 1 (tenant CRUD, Agent Designer, Auth.js v5).
|
||||||
|
|
||||||
|
</domain>
|
||||||
|
|
||||||
|
<decisions>
|
||||||
|
## Implementation Decisions
|
||||||
|
|
||||||
|
### Channel Connection Wizard
|
||||||
|
- Slack connection via standard OAuth2 "Add to Slack" flow — operator clicks button, authorizes, tokens stored automatically
|
||||||
|
- WhatsApp connection: Claude's discretion (guided manual setup or embedded signup — whichever is practical for v1)
|
||||||
|
- After connecting a channel, the wizard MUST include a "send test message" step — required, not optional
|
||||||
|
- Test message verifies end-to-end connectivity before the agent goes live
|
||||||
|
|
||||||
|
### Onboarding Flow
|
||||||
|
- Onboarding sequence: Connect Channel → Configure Agent → Send Test Message
|
||||||
|
- Agent goes live automatically after the test message succeeds — no separate "Go Live" button
|
||||||
|
- Stepper UI / progress indicator: Claude's discretion
|
||||||
|
- Onboarding target: complete in under 15 minutes (from roadmap success criteria)
|
||||||
|
|
||||||
|
### Billing & Pricing
|
||||||
|
- Pricing model: per-agent monthly (e.g., $49/agent/month) — matches the "hire an employee" metaphor
|
||||||
|
- 14-day free trial with full access, credit card required upfront
|
||||||
|
- Subscription management via Stripe: subscribe, upgrade (add agents), downgrade (remove agents), cancel
|
||||||
|
- Enforcement on non-payment: Claude's discretion (agent deactivation recommended — clean, not punitive)
|
||||||
|
- LLM-03 resolved: BYO API keys IS in v1 scope (Phase 3)
|
||||||
|
- BYO key management: Claude's discretion (settings page vs per-agent — settings page simpler for v1)
|
||||||
|
|
||||||
|
### Cost Dashboard
|
||||||
|
- Metrics displayed: token usage per agent, cost breakdown by LLM provider, message volume per agent/channel, budget alerts
|
||||||
|
- Budget alerts: visual indicator when approaching or exceeding per-agent budget limits (from AGNT-07)
|
||||||
|
- Time range selector: Claude's discretion
|
||||||
|
- Dashboard lives in the portal as a dedicated section
|
||||||
|
|
||||||
|
### Claude's Discretion
|
||||||
|
- WhatsApp connection method (guided manual vs embedded signup)
|
||||||
|
- Stepper UI for onboarding (yes/no, visual style)
|
||||||
|
- Non-payment enforcement behavior
|
||||||
|
- BYO key scope (tenant-level settings page vs per-agent)
|
||||||
|
- Cost dashboard time range options
|
||||||
|
- Dashboard chart library (recharts, nivo, etc.)
|
||||||
|
- Stripe webhook event handling strategy (idempotency, retry)
|
||||||
|
|
||||||
|
</decisions>
|
||||||
|
|
||||||
|
<specifics>
|
||||||
|
## Specific Ideas
|
||||||
|
|
||||||
|
- The "per-agent monthly" pricing reinforces the "hire an employee" brand — operators think in terms of headcount, not API calls
|
||||||
|
- The 14-day trial should feel generous — full access to everything, no artificial limits
|
||||||
|
- Channel connection should feel like the easiest part — one click for Slack, guided steps for WhatsApp
|
||||||
|
- Cost dashboard should answer "how much is this employee costing me?" at a glance — like a payroll view
|
||||||
|
|
||||||
|
</specifics>
|
||||||
|
|
||||||
|
<code_context>
|
||||||
|
## Existing Code Insights
|
||||||
|
|
||||||
|
### Reusable Assets
|
||||||
|
- `packages/portal/` — Full Next.js 16 portal with Auth.js v5, tenant CRUD, Agent Designer
|
||||||
|
- `packages/portal/lib/auth.ts` — Auth.js v5 Credentials provider with JWT strategy
|
||||||
|
- `packages/portal/lib/api.ts` — API client for FastAPI backend
|
||||||
|
- `packages/portal/lib/queries.ts` — TanStack Query hooks for tenant/agent CRUD
|
||||||
|
- `packages/portal/components/agent-designer.tsx` — Agent Designer form with all fields
|
||||||
|
- `packages/shared/shared/api/portal.py` — FastAPI portal router (11 endpoints)
|
||||||
|
- `packages/shared/shared/models/tenant.py` — Tenant and Agent SQLAlchemy models
|
||||||
|
- `packages/shared/shared/models/audit.py` — AuditEvent model (source for cost/usage data)
|
||||||
|
- `packages/orchestrator/orchestrator/audit/logger.py` — Audit logger (logs LLM calls, tool invocations)
|
||||||
|
- `packages/shared/shared/config.py` — Centralized settings
|
||||||
|
|
||||||
|
### Established Patterns
|
||||||
|
- Portal pages: App Router with `(dashboard)` route group, TanStack Query for data fetching
|
||||||
|
- API endpoints: FastAPI router in `shared/api/portal.py`
|
||||||
|
- Auth: Auth.js v5 JWT with Credentials provider
|
||||||
|
- Forms: react-hook-form + zod + standardSchemaResolver
|
||||||
|
- Components: shadcn/ui
|
||||||
|
- Proxy: `proxy.ts` (Next.js 16 pattern, not middleware.ts)
|
||||||
|
|
||||||
|
### Integration Points
|
||||||
|
- Portal needs new pages: channel wizard, onboarding flow, billing management, cost dashboard
|
||||||
|
- FastAPI needs new endpoints: channel connection (OAuth callback), Stripe webhooks, usage aggregation
|
||||||
|
- Agent model needs: `is_active` field for subscription enforcement
|
||||||
|
- Tenant model needs: `stripe_customer_id`, `subscription_status`, `trial_ends_at` fields
|
||||||
|
- New DB table or extension for BYO encrypted API keys
|
||||||
|
|
||||||
|
</code_context>
|
||||||
|
|
||||||
|
<deferred>
|
||||||
|
## Deferred Ideas
|
||||||
|
|
||||||
|
None — discussion stayed within phase scope
|
||||||
|
|
||||||
|
</deferred>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Phase: 03-operator-experience*
|
||||||
|
*Context gathered: 2026-03-24*
|
||||||
Reference in New Issue
Block a user