243 lines
13 KiB
Markdown
243 lines
13 KiB
Markdown
# Requirements: Konstruct
|
||
|
||
**Defined:** 2026-03-23
|
||
**Core Value:** An AI employee that works in the channels your team already uses — no new tools to learn, no dashboards to check, just a capable coworker in Slack or WhatsApp.
|
||
|
||
## v1 Requirements
|
||
|
||
Requirements for beta-ready release. Each maps to roadmap phases.
|
||
|
||
### Channel Infrastructure
|
||
|
||
- [x] **CHAN-01**: Channel Gateway normalizes messages from all channels into unified KonstructMessage format
|
||
- [x] **CHAN-02**: User can interact with AI employee via Slack (Events API — @mentions, DMs, thread replies)
|
||
- [x] **CHAN-03**: User can interact with AI employee via WhatsApp Business Cloud API
|
||
- [x] **CHAN-04**: WhatsApp adapter enforces business-function scoping per Meta 2026 policy
|
||
- [x] **CHAN-05**: Platform rate-limits requests per tenant and per channel with configurable thresholds
|
||
|
||
### Agent Core
|
||
|
||
- [x] **AGNT-01**: Tenant can configure a single AI employee with custom name, role, and persona
|
||
- [x] **AGNT-02**: Agent maintains conversational memory within sessions (sliding window)
|
||
- [x] **AGNT-03**: Agent retrieves relevant past context via vector search (pgvector long-term memory)
|
||
- [x] **AGNT-04**: Agent can invoke registered tools to perform actions (tool registry + execution)
|
||
- [x] **AGNT-05**: Agent escalates to human when configured rules trigger, transferring full conversation context
|
||
- [x] **AGNT-06**: Every agent action (LLM call, tool invocation, handoff) is logged in an audit trail
|
||
- [x] **AGNT-07**: Agent token usage is tracked per-agent per-tenant with configurable budget limits
|
||
|
||
### LLM Backend
|
||
|
||
- [x] **LLM-01**: LiteLLM router abstracts LLM provider selection with fallback routing
|
||
- [x] **LLM-02**: Platform supports Ollama (local) and commercial APIs (Anthropic, OpenAI) as LLM providers
|
||
- [x] **LLM-03**: Tenant can provide their own API keys for supported LLM providers (BYO keys, encrypted at rest)
|
||
|
||
### Multi-Tenancy & Security
|
||
|
||
- [x] **TNNT-01**: All tenant data is isolated via PostgreSQL Row Level Security
|
||
- [x] **TNNT-02**: Inbound messages are resolved to the correct tenant via channel metadata
|
||
- [x] **TNNT-03**: Per-tenant Redis namespace isolation for cache and session state
|
||
- [x] **TNNT-04**: All data encrypted at rest (PostgreSQL, object storage) and in transit (TLS 1.3)
|
||
|
||
### Admin Portal
|
||
|
||
- [x] **PRTA-01**: Operator can create, view, update, and delete tenants
|
||
- [x] **PRTA-02**: Operator can design agents via a dedicated Agent Designer module — defining job description, statement of work, persona, system prompt, tool assignments, and escalation rules
|
||
- [x] **PRTA-03**: Operator can connect messaging channels (Slack, WhatsApp) via guided wizard
|
||
- [x] **PRTA-04**: New tenants are guided through structured onboarding (connect channel, configure agent, test message)
|
||
- [x] **PRTA-05**: Operator can manage subscription plans and billing via Stripe integration
|
||
- [x] **PRTA-06**: Portal displays agent cost tracking and usage metrics per tenant
|
||
|
||
### RBAC & User Management
|
||
|
||
- [x] **RBAC-01**: Platform admin role with full access to all tenants, agents, users, and platform settings
|
||
- [x] **RBAC-02**: Customer admin role scoped to a single tenant with full control over agents, channels, billing, API keys, and user management
|
||
- [x] **RBAC-03**: Customer operator role scoped to a single tenant with read-only access to agents, conversations, and usage dashboards
|
||
- [x] **RBAC-04**: Customer admin can invite users (admin or operator) by email — invitee receives activation link to set password and enable access
|
||
- [x] **RBAC-05**: Portal navigation, pages, and UI elements adapt based on user role (platform admin sees tenant picker, customer admin sees their tenant, operator sees read-only views)
|
||
- [x] **RBAC-06**: API endpoints enforce role-based authorization — unauthorized actions return 403 Forbidden, not just hidden UI
|
||
|
||
### Employee Design
|
||
|
||
- [x] **EMPL-01**: Multi-step wizard guides user through AI employee creation (role definition, persona, tools, channels, escalation rules) without requiring knowledge of system prompt format
|
||
- [x] **EMPL-02**: Pre-built agent templates (e.g., Customer Support Rep, Sales Assistant, Office Manager) available for one-click deployment with sensible defaults
|
||
- [x] **EMPL-03**: Template-deployed agents are immediately functional — respond in connected channels with the template's persona, tools, and escalation rules
|
||
- [x] **EMPL-04**: Wizard and templates accessible to platform admins and customer admins (RBAC-enforced, not operators)
|
||
- [x] **EMPL-05**: Agents created via wizard or template appear in Agent Designer for further customization
|
||
|
||
### Web Chat
|
||
|
||
- [x] **CHAT-01**: Users can open a chat window with any AI Employee and have a real-time conversation within the portal
|
||
- [x] **CHAT-02**: Web chat supports the full agent pipeline — memory, tools, escalation, and media (same capabilities as Slack/WhatsApp)
|
||
- [x] **CHAT-03**: Conversation history persists and is visible when the user returns to the chat
|
||
- [x] **CHAT-04**: Chat respects RBAC — users can only chat with agents belonging to tenants they have access to
|
||
- [x] **CHAT-05**: Chat interface feels responsive — typing indicators, message streaming or fast response display
|
||
|
||
### Multilanguage
|
||
|
||
- [x] **I18N-01**: Portal UI fully localized in English, Spanish, and Portuguese (all pages, labels, buttons, error messages)
|
||
- [x] **I18N-02**: Language switcher accessible from anywhere in the portal — selection persists across sessions
|
||
- [x] **I18N-03**: AI Employees detect user language and respond accordingly, or use a language configured per agent
|
||
- [x] **I18N-04**: Agent templates, wizard steps, and onboarding flow are fully translated in all three languages
|
||
- [x] **I18N-05**: Error messages, validation text, and system notifications are localized
|
||
- [x] **I18N-06**: Adding a new language requires only translation files, not code changes (extensible i18n architecture)
|
||
|
||
### Mobile + PWA
|
||
|
||
- [x] **MOB-01**: All portal pages render correctly and are usable on mobile (320px–480px) and tablet (768px–1024px) screens
|
||
- [x] **MOB-02**: Sidebar collapses to a bottom tab bar on mobile with smooth navigation and More sheet for secondary items
|
||
- [x] **MOB-03**: Chat interface is fully functional on mobile — send messages, see streaming responses, scroll history
|
||
- [x] **MOB-04**: Portal installable as a PWA with app icon, splash screen, and service worker for offline shell caching
|
||
- [x] **MOB-05**: Push notifications for new messages when PWA is installed (or service worker caches app shell for instant load)
|
||
- [x] **MOB-06**: All touch interactions feel native — no hover-dependent UI that breaks on touch devices
|
||
|
||
### Testing & QA
|
||
|
||
- [x] **QA-01**: Playwright E2E tests cover all critical user flows (login, tenant CRUD, agent deploy, chat, billing, RBAC)
|
||
- [x] **QA-02**: Lighthouse scores >= 90 for performance, accessibility, best practices, and SEO on key pages
|
||
- [x] **QA-03**: Visual regression snapshots at desktop (1280px), tablet (768px), and mobile (375px) for all key pages
|
||
- [x] **QA-04**: axe-core accessibility audit passes with zero critical violations across all pages
|
||
- [x] **QA-05**: E2E tests pass on Chrome, Firefox, and Safari (WebKit) via Playwright
|
||
- [x] **QA-06**: Empty states, error states, and loading states tested and rendered correctly
|
||
- [x] **QA-07**: CI-ready test suite runnable in GitHub Actions / Gitea Actions pipeline
|
||
|
||
### Agent Capabilities
|
||
|
||
- [x] **CAP-01**: Web search tool returns real results from a search provider (Brave Search, SerpAPI, or similar)
|
||
- [x] **CAP-02**: Knowledge base tool searches tenant-scoped documents that have been uploaded, chunked, and embedded in pgvector
|
||
- [x] **CAP-03**: Operators can upload documents (PDF, DOCX, TXT) to a tenant's knowledge base via the portal
|
||
- [x] **CAP-04**: HTTP request tool can call operator-configured URLs with response parsing and timeout handling
|
||
- [x] **CAP-05**: Calendar tool can check Google Calendar availability (read-only for v1)
|
||
- [x] **CAP-06**: Tool results are incorporated naturally into agent responses — no raw JSON or technical output shown to users
|
||
- [x] **CAP-07**: All tool invocations are logged in the audit trail with input parameters and output summary
|
||
|
||
## v2 Requirements
|
||
|
||
Deferred to future release. Tracked but not in current roadmap.
|
||
|
||
### Channel Expansion
|
||
|
||
- **CHAN-06**: User can interact with AI employee via Microsoft Teams
|
||
- **CHAN-07**: User can interact with AI employee via Mattermost
|
||
- **CHAN-08**: User can interact with AI employee via Telegram
|
||
|
||
### Agent Advanced
|
||
|
||
- **AGNT-08**: Same agent maintains unified memory across Slack and WhatsApp (cross-channel identity)
|
||
- **AGNT-09**: Agent detects negative sentiment and proactively escalates before user requests it
|
||
- **AGNT-10**: Pre-built tool integrations for common SMB tools (Zendesk, HubSpot, Google Calendar)
|
||
|
||
### Multi-Agent Teams
|
||
|
||
- **TEAM-01**: Coordinator agent routes inbound messages to specialist agents
|
||
- **TEAM-02**: Specialist agents execute domain-specific tasks and return results to coordinator
|
||
- **TEAM-03**: All inter-agent communication logged for audit
|
||
|
||
### Enterprise
|
||
|
||
- **ENTR-01**: Schema-per-tenant isolation for Team tier
|
||
- **ENTR-02**: Self-hosted deployment via Helm chart and Docker Compose
|
||
- **ENTR-03**: Agent marketplace with pre-built role templates
|
||
|
||
## Out of Scope
|
||
|
||
| Feature | Reason |
|
||
|---------|--------|
|
||
| Voice/telephony channels (Twilio) | Completely different tech stack and regulatory environment; validate messaging first |
|
||
| Open-ended general-purpose WhatsApp bot | Banned by Meta (Jan 2026 policy); agents must serve specific business functions |
|
||
| Real-time token streaming in chat | Slack/WhatsApp don't support partial message streaming; zero user benefit |
|
||
| Full no-code visual agent builder (drag-and-drop) | Agent Designer covers structured text-based configuration; visual flow builders are premature |
|
||
| Cross-tenant agent communication | Security/isolation violation; no compliance framework supports it |
|
||
| Dashboard-first UX for end users | Defeats core value proposition; agent interactions stay in messaging channels |
|
||
| White-labeling for agencies | Secondary market; validate direct SMB first |
|
||
| AI company hierarchy (teams of teams) | Requires proven multi-agent foundation; v3+ |
|
||
| SOC 2 / HIPAA compliance | Post-revenue; self-hosted option covers compliance-sensitive customers |
|
||
|
||
## Traceability
|
||
|
||
Which phases cover which requirements. Updated during roadmap creation.
|
||
|
||
| Requirement | Phase | Status |
|
||
|-------------|-------|--------|
|
||
| CHAN-01 | Phase 1 | Complete |
|
||
| CHAN-02 | Phase 1 | Complete |
|
||
| CHAN-03 | Phase 2 | Complete |
|
||
| CHAN-04 | Phase 2 | Complete |
|
||
| CHAN-05 | Phase 1 | Complete |
|
||
| AGNT-01 | Phase 1 | Complete |
|
||
| AGNT-02 | Phase 2 | Complete |
|
||
| AGNT-03 | Phase 2 | Complete |
|
||
| AGNT-04 | Phase 2 | Complete |
|
||
| AGNT-05 | Phase 2 | Complete |
|
||
| AGNT-06 | Phase 2 | Complete |
|
||
| AGNT-07 | Phase 3 | Complete |
|
||
| LLM-01 | Phase 1 | Complete |
|
||
| LLM-02 | Phase 1 | Complete |
|
||
| LLM-03 | Phase 3 | Complete |
|
||
| TNNT-01 | Phase 1 | Complete |
|
||
| TNNT-02 | Phase 1 | Complete |
|
||
| TNNT-03 | Phase 1 | Complete |
|
||
| TNNT-04 | Phase 1 | Complete |
|
||
| PRTA-01 | Phase 1 | Complete |
|
||
| PRTA-02 | Phase 1 | Complete |
|
||
| PRTA-03 | Phase 3 | Complete |
|
||
| PRTA-04 | Phase 3 | Complete |
|
||
| PRTA-05 | Phase 3 | Complete |
|
||
| PRTA-06 | Phase 3 | Complete |
|
||
| RBAC-01 | Phase 4 | Complete |
|
||
| RBAC-02 | Phase 4 | Complete |
|
||
| RBAC-03 | Phase 4 | Complete |
|
||
| RBAC-04 | Phase 4 | Complete |
|
||
| RBAC-05 | Phase 4 | Complete |
|
||
| RBAC-06 | Phase 4 | Complete |
|
||
| EMPL-01 | Phase 5 | Complete |
|
||
| EMPL-02 | Phase 5 | Complete |
|
||
| EMPL-03 | Phase 5 | Complete |
|
||
| EMPL-04 | Phase 5 | Complete |
|
||
| EMPL-05 | Phase 5 | Complete |
|
||
| CHAT-01 | Phase 6 | Complete |
|
||
| CHAT-02 | Phase 6 | Complete |
|
||
| CHAT-03 | Phase 6 | Complete |
|
||
| CHAT-04 | Phase 6 | Complete |
|
||
| CHAT-05 | Phase 6 | Complete |
|
||
| I18N-01 | Phase 7 | Complete |
|
||
| I18N-02 | Phase 7 | Complete |
|
||
| I18N-03 | Phase 7 | Complete |
|
||
| I18N-04 | Phase 7 | Complete |
|
||
| I18N-05 | Phase 7 | Complete |
|
||
| I18N-06 | Phase 7 | Complete |
|
||
|
||
| MOB-01 | Phase 8 | Complete |
|
||
| MOB-02 | Phase 8 | Complete |
|
||
| MOB-03 | Phase 8 | Complete |
|
||
| MOB-04 | Phase 8 | Complete |
|
||
| MOB-05 | Phase 8 | Complete |
|
||
| MOB-06 | Phase 8 | Complete |
|
||
| QA-01 | Phase 9 | Complete |
|
||
| QA-02 | Phase 9 | Complete |
|
||
| QA-03 | Phase 9 | Complete |
|
||
| QA-04 | Phase 9 | Complete |
|
||
| QA-05 | Phase 9 | Complete |
|
||
| QA-06 | Phase 9 | Complete |
|
||
| QA-07 | Phase 9 | Complete |
|
||
| CAP-01 | Phase 10 | Complete |
|
||
| CAP-02 | Phase 10 | Complete |
|
||
| CAP-03 | Phase 10 | Complete |
|
||
| CAP-04 | Phase 10 | Complete |
|
||
| CAP-05 | Phase 10 | Complete |
|
||
| CAP-06 | Phase 10 | Complete |
|
||
| CAP-07 | Phase 10 | Complete |
|
||
|
||
**Coverage:**
|
||
- v1 requirements: 25 total (all complete)
|
||
- RBAC requirements: 6 total (Phase 4, all complete)
|
||
- Employee Design requirements: 5 total (Phase 5, all complete)
|
||
- Web Chat requirements: 5 total (Phase 6, all complete)
|
||
- Multilanguage requirements: 6 total (Phase 7, all complete)
|
||
- Mobile + PWA requirements: 6 total (Phase 8, all complete)
|
||
- Testing & QA requirements: 7 total (Phase 9, all complete)
|
||
- Agent Capabilities requirements: 7 total (Phase 10)
|
||
|
||
---
|
||
*Requirements defined: 2026-03-23*
|
||
*Last updated: 2026-03-23 after roadmap creation — traceability complete*
|