konstruct/.planning/ROADMAP.md

Roadmap: Konstruct

Overview

Konstruct ships in three coarse phases ordered by dependency: first build the secure multi-tenant pipeline and prove that a Slack message triggers an LLM response (Phase 1 — Foundation), then add the agent capabilities that make it a real product: memory, tools, WhatsApp, and escalation (Phase 2 — Agent Features), then complete the operator-facing experience so tenants can self-onboard and pay (Phase 3 — Operator Experience). Phase 3 is gated on DB schema stability, which only exists after Phase 2 defines the memory and tool data models.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Foundation - Secure multi-tenant pipeline with Slack end-to-end and basic agent response (completed 2026-03-23)
• Phase 2: Agent Features - Persistent memory, tool framework, WhatsApp integration, and human escalation (gap closure in progress) (completed 2026-03-24)
• Phase 3: Operator Experience - Admin portal, tenant onboarding, and Stripe billing (gap closure in progress)
• Phase 4: RBAC - Three-tier role-based access control with email invitation flow

Phase Details

Phase 1: Foundation

Goal: Operators can deploy the platform, a Slack message triggers an LLM response back in-thread, and no tenant can ever see another tenant's data Depends on: Nothing (first phase) Requirements: CHAN-01, CHAN-02, CHAN-05, AGNT-01, LLM-01, LLM-02, TNNT-01, TNNT-02, TNNT-03, TNNT-04, PRTA-01, PRTA-02 Success Criteria (what must be TRUE):

1. A user can send a Slack @mention or DM to the AI employee and receive a coherent reply in the same thread — end-to-end in under 30 seconds
2. Tenant A's messages, agent configuration, and conversation data are completely invisible to Tenant B — verified by integration tests with two-tenant fixtures
3. A request that exceeds the per-tenant or per-channel rate limit is rejected with an informative response rather than silently dropped
4. The LLM backend pool routes requests through LiteLLM to both Ollama (local) and Anthropic/OpenAI, with automatic fallback when a provider is unavailable
5. A new AI employee can be configured with a custom name, role, and persona — and that persona is reflected in responses
6. An operator can create tenants and design agents (name, role, persona, system prompt, tools, escalation rules) via the admin portal Plans: 4 plans

Plans:

• 01-01: Monorepo scaffolding, Docker Compose dev environment, shared Pydantic models, DB schema with RLS
• 01-02: LiteLLM backend pool service with Ollama + Anthropic/OpenAI providers and Celery async dispatch
• 01-03: Channel Gateway (Slack adapter), Message Router (tenant resolution), basic Agent Orchestrator (single agent, no memory/tools)
• 01-04: Next.js admin portal with Auth.js v5, tenant CRUD, and Agent Designer module

Phase 2: Agent Features

Goal: The AI employee maintains conversation memory, can execute tools, handles WhatsApp messages, and escalates to humans when rules trigger — making it a capable product rather than a demo Depends on: Phase 1 Requirements: CHAN-03, CHAN-04, AGNT-02, AGNT-03, AGNT-04, AGNT-05, AGNT-06 Success Criteria (what must be TRUE):

1. The AI employee remembers context from earlier in the same conversation and can reference it accurately — tested at 30+ conversation turns without degradation
2. A user can send a WhatsApp message to the AI employee and receive a reply — with per-tenant phone number isolation and business-function scoping enforced per Meta 2026 policy
3. The agent can invoke a registered tool (e.g., knowledge base search) and incorporate the result into its response
4. When a configured escalation rule triggers (e.g., failed resolution attempts), the conversation and full context are handed off to a human with no information lost
5. Every LLM call, tool invocation, and handoff event is recorded in an immutable audit trail queryable by tenant Plans: 6 plans

Plans:

• 02-01: Conversational memory layer (Redis sliding window + pgvector long-term storage with HNSW index)
• 02-02: Tool framework (registry, schema-validated execution, audit logging) — split into audit+tools+wiring
• 02-03: WhatsApp adapter (Business Cloud API, per-tenant phone numbers, media download, Meta policy compliance)
• 02-04: Human escalation/handoff with full context transfer and audit trail
• 02-05: Cross-channel media support and multimodal LLM interpretation (Slack file_share, image_url content blocks, channel-aware outbound routing)
• 02-06: Gap closure — re-wire escalation handler and WhatsApp outbound routing into pipeline, add tier-2 system prompt scoping

Phase 3: Operator Experience

Goal: An operator can sign up, onboard their tenant through a web UI, connect their messaging channels, configure their AI employee, and manage their subscription — without touching config files or the command line Depends on: Phase 2 Requirements: AGNT-07, LLM-03, PRTA-03, PRTA-04, PRTA-05, PRTA-06 Success Criteria (what must be TRUE):

1. An operator can connect Slack and WhatsApp to their tenant through a guided in-portal wizard without reading documentation
2. A new tenant completes the full onboarding sequence (connect channel -> configure agent -> send test message) in under 15 minutes
3. An operator can subscribe, upgrade, and cancel their plan through Stripe — and feature limits are enforced automatically based on subscription state
4. The portal displays per-tenant agent cost and token usage, giving operators visibility into spending without requiring access to backend logs Plans: 5 plans

Plans:

• 03-01-PLAN.md — Backend foundation: DB migrations, billing models, encryption service, channel/billing/usage API endpoints, audit logger token metadata
• 03-02-PLAN.md — Channel connection wizard (Slack OAuth + WhatsApp manual), onboarding flow with 3-step stepper, BYO API key settings page
• 03-03-PLAN.md — Stripe billing page with subscription management, status badges, Checkout and Billing Portal redirects
• 03-04-PLAN.md — Cost tracking dashboard with Recharts charts, budget alert badges, time range filtering
• 03-05-PLAN.md — Gap closure: mount Phase 3 API routers on gateway, fix Slack OAuth and budget alert field name mismatches (completed 2026-03-24)

Phase 4: RBAC

Goal: Three-tier role-based access control — platform admins manage the SaaS, customer admins manage their tenant, customer operators get read-only access — with email invitation flow for onboarding tenant users Depends on: Phase 3 Requirements: RBAC-01, RBAC-02, RBAC-03, RBAC-04, RBAC-05, RBAC-06 Success Criteria (what must be TRUE):

1. A platform admin can see all tenants, all agents, and all users across the entire platform
2. A customer admin can only see their own tenant's agents, users, billing, and settings — no cross-tenant visibility
3. A customer operator can view agents and usage dashboards but cannot create, edit, or delete anything
4. A customer admin can invite a new user (admin or operator) by email — the invitee receives a link, clicks to activate, and sets their password
5. Portal navigation and API endpoints enforce role-based access — unauthorized actions return 403, not just hidden UI elements Plans: 3 plans

Plans:

• 04-01-PLAN.md — Backend RBAC foundation: DB migration (is_admin -> role enum), ORM models (UserTenantRole, PortalInvitation), RBAC guard dependencies, invitation API + SMTP email, unit tests
• 04-02-PLAN.md — Portal RBAC integration: Auth.js JWT role claims, proxy role redirects, role-filtered nav, tenant switcher, impersonation banner, invite acceptance page, user management pages
• 04-03-PLAN.md — Wire RBAC guards to all existing API endpoints, impersonation audit logging, integration tests, human verification checkpoint

Progress

Execution Order: Phases execute in numeric order: 1 -> 2 -> 3 -> 4

Phase	Plans Complete	Status	Completed
1. Foundation	4/4	Complete	2026-03-23
2. Agent Features	6/6	Complete	2026-03-24
3. Operator Experience	5/5	Complete	2026-03-24
4. RBAC	1/3	In Progress

---

Coverage Notes

LLM-03 conflict resolved: BYO API keys confirmed in v1 scope per user decision during Phase 3 context gathering. Implemented via Fernet encryption in Phase 3.

---

Roadmap created: 2026-03-23 Coverage: 25/25 v1 requirements + 6 RBAC requirements mapped