SASVA Canvas

AI-Powered Product Planning & Business Intelligence Platform

165+

API Routes

25+

AI Agents

20+

Integrations

12+

Operations

Platforms

What is SASVA Canvas?

On-premise AI platform for product teams and business analysts — connect enterprise systems, run AI operations, and collaborate with multi-agent intelligence

🔗

Enterprise Connectivity

JIRA, GitHub, GitLab, Azure DevOps, Bitbucket, ServiceNow, Confluence, SharePoint, Salesforce, HubSpot, Dynamics, Slack, SerpAPI — OAuth 2.0 PKCE with legacy fallback.

🔒

Security & Compliance

Azure AD SSO, RBAC (4 roles), Ed25519 signing, PII masking, rate limiting, account lockout, AUDIT logging, tenant isolation, air-gapped bundles.

📁

Workspaces

Product, Business, and Assessment workspaces — independent chat histories, connection slots, LanceDB indexing, sharing (Viewer/Editor/Admin).

🤖

Multi-Agent RAG

Retrieval → Verify → Fact-Check → Latest-Check → role agents. Extended Thinking, citations, fast-path, streaming SSE.

📋 Complete Platform Capabilities

✅
Release Planning — Use cases → EPICs → stories → SASVA or Advanced Estimation Engine → publish to JIRA/Aha!/Asana/Azure DevOps. Planning drafts persist sessions.
✅
8-Factor ROI — Deterministic NPV, IRR, TCO, payback. Revenue impact, cost reduction, retention, market position, strategic alignment, implementation cost, risk, customer demand. SSE streaming via /api/operations/roi-analysis/stream.
✅
Code & Process Assessment — Assessment Portal (28 agents, 10 phases): complexity, hotspots, SAST, CVE, SBOM, developer profiling, portfolio reports. Modes: code, security, full.
✅
Business Operations — Proposals, business analysis, meeting prep, presentations, customer analysis (CRM), competitive research with SerpAPI.
✅
Document Intelligence — 16+ formats, Python processor (:3302), OCR (Tesseract + vision), 16 classifiers, spaCy NER, knowledge graph, 50K chunk cap per workspace.
✅
Collaboration — Artifacts with comments, versions, collaborators, approval workflow. In-app notifications. Knowledge chat for follow-up on operation results.
✅
Email & Feedback — Lifecycle emails (user, workspace, operations). Thumbs up/down. Help Center threads. Admin feedback CSV export.
✅
Observability — 17 log categories, 6 levels, PostHog (~40 events), gateway telemetry v1.3, lifecycle dashboard, /api/admin/metrics.
✅
Billing — Stripe + Braintree, Free/Starter/Professional/Enterprise, 24 feature keys, dunning, invoices, webhooks, 3D Secure.
✅
Clients — Web (:3300), Desktop (Electron 33, ctx-code, safeStorage), Mobile (Expo, voice dictation, business workspaces).

Workspace Types

Product and Business workspaces — independent containers with dedicated connectors, operations, personas, and outputs

Each workspace has its own chat history, connection slots, indexed content, operation results, and team sharing. Workspaces are not nested — create one per product line, customer, or initiative. Limits per billing plan (Free: 1, Starter: 5, Pro: 20, Enterprise: unlimited).

💻

Product Workspace

For software development teams — release planning, code assessment, backlog, estimation, and ALM push-back.

Project types: Brownfield (existing product) · Greenfield (new product)

💼

Business Workspace

For business analysis — document RAG, proposals, CRM-aware research, market intelligence, and report generation.

Focus: Business vertical, customer-facing deliverables

📋 Feature Comparison

Dimension	Product Workspace	Business Workspace
Primary Personas	Product Manager, Business Analyst, Architect, Developer, QA Engineer, Security Analyst, Program Manager, UX Designer	Business Analyst, Proposal Writer, Sales/Account Manager, Content Writer, Customer Success, Executive Sponsor
Operations	Release Planning · Market Insights · ROI & Business Value · Backlog Assessment · Code Assessment · Process Assessment · Capacity Planning · Technical Debt Review · Security Review · Genesis Discovery	Create Proposal · Business Analysis · Meeting Preparation · Create Presentation · Customer Analysis · Competitive Research · Market Research (SerpAPI)
Connection Slots	processManagement — JIRA, Asana, Aha!, Azure DevOps, Monday.com codeRepository — GitHub, GitLab, Bitbucket, Azure Repos, Local upload ticketingSystem — ServiceNow, Zendesk, Freshdesk, JIRA Service Desk documentation — Confluence, SharePoint, File Upload	documentSources[] — SharePoint (OAuth), Confluence (OAuth), Google Drive, Notion, Local Files, Website crawl crmSystem — Salesforce, HubSpot, Zoho, Dynamics communication — Outlook, Gmail, Slack, Teams researchWebsites[] — URLs + SerpAPI
Indexing Sources	Code repositories (clone/local), connected documentation, PM tool exports, uploaded files	Uploaded documents (16+ formats), connected drives, Confluence/SharePoint pages, website URLs, CRM records, pasted images (OCR)
Primary Outputs	Release plans · Use cases · EPICs & stories · Effort estimates · ROI reports · Backlog items · Code/process assessment reports · JIRA/Aha!/Asana/Azure DevOps exports	Proposals · Business analysis reports · Meeting prep briefs · Presentation outlines · Customer insight reports · Competitive research reports · PDF/HTML/DOCX/PPTX exports
Push to ALM / CRM	✅ Publish release plan, push backlog items, push to JIRA — targets JIRA, Aha!, Asana, Azure DevOps	✅ CRM read context (Salesforce, HubSpot, Dynamics) — outputs are documents/reports, not ticket push-back
Estimation Engine	✅ SASVA Models or Advanced Estimation Engine (:8100) — EPIC/story breakdown, effort estimation, sprint planning	—
Assessment Portal	✅ Code Assessment operation — connects to Assessment Portal (:9000) for code/security/full scan modes	—
Image / Diagram Gen	✅ Mermaid diagrams, architecture diagrams, creative images in chat	✅ Creative images, diagrams, OCR on uploaded images
Knowledge Graph	✅ Entity resolution across code + docs	✅ Entity resolution across documents + web sources
Market Research	✅ SerpAPI — trends, news, scholar	✅ SerpAPI + inline URL fetch
Sharing	✅ Viewer / Editor / Admin permissions	✅ Viewer / Editor / Admin permissions
Separate Chat History	✅ Per workspace	✅ Per workspace
Artifact Review	✅ Draft → in_review → approved workflow with comments & versions	✅ Draft → in_review → approved workflow with comments & versions

🔗 Connection Slot Reference

Slot Key	Product	Business	Auth Mode
`processManagement`	JIRA, Asana, Aha!, Azure DevOps	—	OAuth (Atlassian) or PAT/API token
`codeRepository`	GitHub, GitLab, Bitbucket, Azure Repos, Local	—	PAT / token
`ticketingSystem`	ServiceNow, Zendesk, Freshdesk	—	Basic auth / API key
`documentation`	Confluence, SharePoint, File Upload	SharePoint, Confluence, drives	OAuth or legacy credentials
`documentSources[]`	—	SharePoint, Confluence, Drive, Notion, Local, Website	Per-source OAuth/token
`crmSystem`	—	Salesforce, HubSpot, Zoho, Dynamics	salesforce_oauth / microsoft_oauth
`communication`	—	Outlook, Gmail, Slack, Teams	OAuth / bot token
`researchWebsites[]`	—	Website URLs	None (public fetch)

🚀 Workspace Lifecycle

Phase	Activities	System Actions
1 · Create & Onboard	Choose type, name, project type (brownfield/greenfield), configure connection slots	Persist workspace blueprint; validate connector credentials via `POST /api/connectors/test`
2 · Index & Sync	Upload documents or connect live sources; clone code repos	Document processor (:3302) extracts, classifies, chunks, embeds → LanceDB; knowledge graph entities extracted; background clone for large repos
3 · Operate	Run operations or chat with multi-agent RAG	Agent orchestration, SSE streaming, artifact storage, email notifications on completion
4 · Review & Assign	Approve artifacts, assign remediation work	Artifact review workflow; optional push to JIRA/ServiceNow; planning drafts persist sessions
5 · Share & Collaborate	Invite team members, comment on artifacts	`POST /api/workspaces/[id]/share`; in-app notifications; email on share events
6 · Steady State	Monitor health, re-index on source changes	Lifecycle dashboard metrics; `GET /api/lifecycle/metrics`; compliance audit export

AI Agents

25+ coordinated agents — retrieval & verification enrich every turn; role agents plan, estimate, and reason over backlog and codebase

Orchestration flow: B1 Data Agents (parallel: Document RAG, KG, Web, Fact) → B2 Fetch Agent → B3 Verification (parallel: Verify, Fact-Check, Latest-Check) → B4 Synthesis (BA/PM/Architect) → B5 LLM Response → parallel: Suggestions | Report | Image. Fast-path bypasses full pipeline for casual queries.

📚 Chat, Retrieval & Verification Agents

Agent	Implementation	Function
Document RAG Agent	LanceDB retrieval	Semantic search across indexed workspace documents and chunks
Knowledge Graph Agent	`graph-store.ts`	Entity/relationship lookup, cross-document connections, entity resolution (spaCy NER)
Web Search Agent	SerpAPI	Real-time web search for temporal/competitive queries (trends, news, scholar)
Fact Service Agent	External verified KB URL	Prioritized source-of-truth queries from curated knowledge base
Fetch Agent	`fetch-agent.ts`	Builds RetrievedContext from query, chunks, metadata for verification
Verify Agent	ctx-code / SASVA Native CLI	Relevance and sufficiency of retrieved context
Fact-Check Agent	ctx-code	Cross-references claims against source documents
Latest-Check Agent	ctx-code	Recency and timeliness assessment of information
Knowledge Agent	LLM reasoning layer	Reasoning over conversation context and retrieved information
Orchestrator	`run-agents.ts`	Runs Verify + Fact-Check + Latest-Check in parallel

💻 Product Development Role Agents

Agent	Focus	Used In
Business Analyst	Market trends, competitors, ROI framing	Release planning, market analysis, ROI
Product Manager	User needs, feature prioritization, roadmap	Release planning, backlog assessment
Program Manager	Timelines, dependencies, resource allocation	Release planning, capacity planning
Architect	Scalability, structure, technical trade-offs	Release planning, code assessment
Developer	Code quality, effort signals, implementation	Code assessment, estimation
QA Engineer	Test strategy, coverage, quality risks	Release planning
Security Analyst	Risk, compliance, security requirements	Release planning, security review
UX Designer	Experience patterns, design considerations	Release planning
Market Insights Agent	Trends, competitors, innovations, analyst reports	Market analysis, backlog assessment
Backlog Assessment Agent	Backlog generation & prioritization	Backlog assessment
Technical Debt Agent	Code quality, debt quantification	Code assessment
Security Review Agent	Vulnerability detection, compliance	Code assessment (security mode)
Process Assessment Agent	Workflow optimization, delivery health	Process assessment
ROI Analysis Agent	Deterministic 8-factor NPV/IRR/TCO/payback	ROI analysis (zero LLM for numbers)
Comprehensive ROI Agent	Multi-dimensional ROI with streaming SSE	ROI analysis comprehensive mode

💼 Business Workspace Agents

Agent	Focus	Operations
Proposal Writer Agent	Proposals, RFP responses	Create Proposal
Business Analyst Agent	SWOT, strategic planning	Business Analysis
Meeting Prep Agent	Agendas, talking points, customer background	Meeting Preparation
Customer Insights Agent	Customer profiling, opportunity scoring	Customer Analysis
Presentation Agent	Slide outlines, storytelling	Create Presentation
Content Writer Agent	Email drafting, document formatting	Create Presentation, proposals

📊 Analysis, Formatting & Output Agents

Report Generation Agent

Executive-grade downloadable reports. PPT-canonical pipeline → DOCX/PDF/XLSX/PPTX exports.

Formatter Agent

Canonical presentation — htmlPresentation, htmlExecutive, markdown with brand consistency.

Reviewer Agent

Automated quality review: Structure, Completeness, Tone, Density, Consistency, Accuracy, No duplicates (max 3 iterations).

Image Generation Agent

Creative images (DALL-E 3 / SASVA), architecture diagrams (LLM→JSON→Puppeteer), Mermaid flowcharts with provenance metadata.

⚙️ CLI-Backed Verification (ctx-code)

Verify, Fact-Check, and Latest-Check agents run via ctx-code / SASVA Native CLI. Configured in Settings → AI Runtime (sasvaCli scopes: canvas, estimation, assessment). Desktop bundles platform-specific ctx-code binaries. Project overlay via cli.json.

Ecosystem Integrations

20+ connectors with OAuth 2.0 PKCE — connect enterprise systems for unified AI-grounded analysis

📋 Integration Catalog

Category	Supported (Production)	Planned / Expanding
Project Management	JIRA, Asana, Aha!, Azure DevOps	Monday.com, Trello
Code Repositories	GitHub, GitLab, Bitbucket, Local upload	Azure Repos, SVN
Ticketing	ServiceNow, Zendesk, Freshdesk, JIRA Service Desk	—
Documentation	Confluence, SharePoint, File Upload	Notion, Google Drive
CRM	Salesforce, HubSpot, Zoho CRM, Microsoft Dynamics	Pipedrive
Communication	Slack	Teams, Outlook, Gmail
Market Research	SerpAPI (Google Trends, News, Scholar)	—
Assessment	Assessment Portal API (:9000)	—
Estimation	Advanced Estimation Engine (:8100)	—

🔐 OAuth 2.0 Connectors (Recommended)

Modern connectors use OAuth 2.0 with PKCE. Tokens stored server-side per user/tenant connection ID — never in workspace JSON.

Provider	Start Endpoint	Purpose	Legacy Fallback
Microsoft Entra	`/api/integrations/microsoft/oauth/start`	SharePoint, Dynamics 365	Client credentials / app-only
Atlassian	`/api/integrations/atlassian/oauth/start`	JIRA Cloud, Confluence	Email + API token (PAT)
Salesforce	`/api/integrations/salesforce/oauth/start`	CRM delegated access	Password grant
Browser MSAL	`/api/integrations/microsoft/register-from-browser`	MSAL browser flow registration	—

📂 Workspace Connection Slots

Slot	Product Workspace	Business Workspace
processManagement	JIRA, Asana, Aha!, Azure DevOps	—
codeRepository	GitHub, GitLab, Bitbucket, Azure Repos, Local	—
ticketingSystem	ServiceNow, Zendesk, Freshdesk	—
documentation	Confluence, SharePoint, File Upload	SharePoint, Confluence, Google Drive, Notion, Local
crmSystem	—	Salesforce, HubSpot, Zoho, Dynamics
communication	—	Outlook, Gmail, Slack, Teams
documentSources[]	—	SharePoint (OAuth), Confluence (OAuth), Drive (service account), Notion (token), Local, Website (URL crawl)
researchWebsites[]	—	Website URLs for market research

🔧 Integration Manager Classes

Type	Client / Integration Class	Auth Mode
JIRA	JiraIntegration, JiraClient	atlassian_oauth or PAT
GitHub	GitHubIntegration, GitHubClient	Personal access token
GitLab	GitLabIntegration, GitLabClient	Personal access token
Bitbucket	Integration manager wrapper	App password / token
Azure DevOps	Integration manager wrapper	PAT
ServiceNow	ServiceNowIntegration, ServiceNowClient	Basic auth
Aha!	AhaIntegration, AhaClient	API key
Asana	AsanaIntegration, AsanaClient	Personal access token
Salesforce	SalesforceClient + OAuth token store	salesforce_oauth
HubSpot	HubSpotClient	API key / OAuth
Dynamics	DynamicsClient	microsoft_oauth
Slack	SlackClient	Bot token

📤 Push-Back & Data Extraction

🚀
Publish Release Plan — POST /api/operations/publish-release-plan → JIRA, Aha!, Asana, Azure DevOps
📋
Push Backlog Items — POST /api/operations/push-backlog-items → connected PM tools
🎫
Push to JIRA — POST /api/operations/push-to-jira — export release plan items
🔗
Extract Ecosystem — POST /api/extract-ecosystem — pull data from all connected systems
✅
Connector Test — POST /api/connectors/test — validate credentials before save
📊
JIRA Release Items — GET /api/jira/release-items — fetch release items from JIRA

Operations

12 formal workspace operations plus extended capabilities — each grounded in workspace connections and multi-agent orchestration

💻 Product Workspace Operations

Operation	ID	Required Connection	Primary Agents	Key APIs
Release Planning	`release-planning`	Process Management	PM, Architect, Security Analyst, QA, UX	`generate-usecases`, `breakdown-epic`, `estimate-effort`, `publish-release-plan`
Market Insights	`market-analysis`	—	Market Insights Agent	`/api/market-research`
ROI & Business Value	`roi-analysis`	—	ROI Analysis, Comprehensive ROI	`roi-analysis`, `roi-analysis-v2`, `roi-analysis/stream`
Backlog Assessment	`backlog-assessment`	—	Backlog Assessment, Market Insights	`generate-backlog`, `backlog`
Code Assessment	`code-assessment`	Code Repository	Technical Debt, Security Review	Assessment Portal direct + `/api/repository/clone`
Process Assessment	`process-assessment`	Process Management	Process Assessment Agent	`extract-ecosystem`, PM tool APIs

💼 Business Workspace Operations

Operation	ID	Required Connection	Primary Agents
Create Proposal	`create-proposal`	—	Proposal Writer, Market Insights
Business Analysis	`create-business-analysis`	—	Business Analyst, Market Insights
Meeting Preparation	`create-meeting-prep`	—	Meeting Prep, Customer Insights
Create Presentation	`create-presentation`	—	Presentation, Content Writer
Customer Analysis	`customer-analysis`	CRM System	Customer Insights, Market Insights
Competitive Research	`competitive-research`	—	Market Insights, Business Analyst

🔄 Extended Capabilities

Capability	Description	API / UI
Discovery & Planning (Genesis)	Embedded discovery iframe with workspace context	`GET /api/runtime-config`
Capacity Planning	Team capacity and resource allocation narratives	`POST /api/operations/capacity-planning`
Technical Debt Review	Mode within code assessment chat	Code Assessment UI
Security Review	SAST/vulnerability mode (code \| security \| full)	Code Assessment UI
Image / Diagram Generation	DALL-E 3, Mermaid, architecture diagrams (LLM→JSON→Puppeteer)	`/api/workspace/generated-image`
Report Generation	PDF, HTML, DOCX, PPTX, MD, XLSX, CSV — Formatter + Reviewer pipeline	`/api/documents/generate`, `/api/tools/generate-file`
Lifecycle Dashboard	SDLC phase mapping, operation usage (7d/30d/90d/all)	`GET /api/lifecycle/metrics`
Knowledge Chat	Follow-up on Market Insights & ROI results	`POST /api/knowledge-chat`
Website Research	Inline URL analysis in chat	`POST /api/research/website`
Team Collaboration	Share AI responses, comments, versions, approvals	`/api/workspaces/[id]/artifacts/*`

🚀 Release Planning Flow (5 Steps)

1 · Use Cases

AI generates use cases from workspace context, connected PM data, and codebase.
POST /api/operations/generate-usecases

2 · EPIC / Story Breakdown

Break down use cases into EPICs and user stories.
POST /api/operations/breakdown-epic, breakdown-detailed

3 · Estimate

SASVA Models — new/greenfield projects.
Advanced Estimation Engine (:8100) — brownfield with cloned repo.
POST /api/operations/estimate-effort, /api/estimation/*

4 · Assign

Assignable users from connected PM tool.
GET /api/operations/process-management/assignable-users

5 · Publish

Push to JIRA, Aha!, Asana, Azure DevOps.
POST /api/operations/publish-release-plan, push-backlog-items, push-to-jira

💰 ROI Analysis — 8 Factors

Deterministic scoring engine (zero LLM for numeric calculations). Factors: Revenue Impact, Cost Reduction, Customer Retention, Competitive & Market Position, Strategic Alignment, Implementation Cost, Risk Assessment, Customer Demand.

Outputs: ROI %, Payback (months), NPV, IRR, Annual Benefit, 3-year TCO, industry benchmark percentile. Scenarios: Conservative / Moderate / Optimistic. What-if levers and adjustable factor weights.

Chat & Collaboration

Streaming multi-agent chat with RAG, citations, extended thinking, PII masking, and workspace-grounded context

💬 Chat Endpoints

Mode	Endpoint	Description
Workspace Chat	`POST /api/workspace/chat`	Single/multi-turn chat grounded in workspace documents, code, integrations
Streaming (SSE)	`POST /api/workspace/chat/stream`	Token-by-token delivery, source citations, agent progress events
Multi-Agent	`POST /api/workspace/multi-agent-chat`	BA, PM, Architect collaborate with retrieval pipeline
Multi-Agent Stream	`POST /api/workspace/multi-agent-chat/stream`	SSE streaming multi-agent collaboration
Knowledge Chat	`POST /api/knowledge-chat`	Follow-up on Market Insights & ROI results (retry, resume, help, reset)
General Chat	`POST /api/chat`	Non-workspace scoped chat

🧠 Intelligence Features

Extended Thinking

Visible AI reasoning ("Thought for Xs"). Enable via enableThinking: true. Reasoning blocks shown before final response.

Source Citations

Document, code, web, and knowledge-graph sources with chunk references. Agent verification reports via GET /api/workspace/agent-report.

Fast-Path Queries

Casual messages bypass full RAG pipeline for instant responses when no retrieval needed (web + desktop).

Stop Generation

Abort in-flight streaming via AbortController. Partial response preserved in chat history.

PII Masking

Business workspace: query-time redaction of EMAIL, PHONE, SSN, PAN, Aadhaar, CREDIT_CARD, IP, PERSON before LLM processing. Default ON.

Image & OCR

Upload/paste images in business chat. Tesseract OCR + vision model fallback. Image extraction in chat flow.

Voice Dictation

Mobile app speech-to-text via useVoiceRecording hook.

Inline URL Analysis

Website research in chat. POST /api/research/website for structured URL fetch and analysis.

Web Search Tool

LLM function calling via lib/tools/web-search.ts for real-time SerpAPI queries during chat.

File Generation

LLM tool → /api/tools/generate-file for in-chat document creation. Download via /api/tools/download-file.

📜 Chat History, Indexing & Reports

Feature	API
Chat history	`GET+POST /api/chat-history`, `GET+PUT+DELETE /api/chat-history/[id]`
Message feedback	`POST /api/chat-history/[id]/feedback`
Document upload	`POST /api/workspace/upload`, `POST /api/documents/upload`
Index workspace	`POST /api/workspace/index`, `GET /api/workspace/index-status`
Customize report	`POST /api/workspace/customize-report`
Derive format	`POST /api/workspace/derive-format`
Generated images	`GET /api/workspace/generated-image`
LLM providers	SASVA (default), AWS Bedrock — Settings → AI Provider

📡 SSE Event Types

event: agent_start      # Agent begins processing
event: agent_progress    # Retrieval/verification progress
event: thinking          # Extended thinking content
event: token             # Streaming text token
event: sources           # Citation sources attached
event: done              # Stream complete with conversationId
event: error             # Error with message

System Architecture

Five-layer on-premise architecture — clients, API, AI orchestration, platform services, data storage

SASVA Canvas deploys on-premise or air-gapped. Clients connect to Next.js (:3300) exposing 165+ API routes with SSE streaming, which orchestrates the AI agent layer, integration manager, document processor, and LanceDB/PostgreSQL stores. Data never leaves the organisation.

ClientsWeb (Next.js 14) · Desktop (Electron 33) · Mobile (Expo)

→

API Layer165+ routes · auth · RBAC · multi-tenancy · SSE

→

Agent Orchestrator25+ agents · retrieval · verification · synthesis

LLM ClientSASVA (default) · AWS Bedrock

Integration Manager20+ connectors · OAuth 2.0 PKCE

Document ProcessorPython FastAPI :3302

SQLite / PostgreSQLUsers · sessions · billing

File System.canvas-data/

LanceDBSharded vectors + knowledge graph

🏗️ Five Architecture Layers

1 · Client / Access Layer

Web AppNext.js 14 · browser · :3300

Desktop AppElectron 33 · PKCE SSO · ctx-code

Mobile AppExpo / React Native · :3301

Authenticationpassword · Azure AD SSO · session cookie

▼

2 · Application & API Layer

Next.js App Router165+ REST routes · SSE streaming

Auth & RBAC4 roles · Ed25519 · rate limiting

Multi-Tenancytenant isolation · per-tenant settings

BillingStripe/Braintree · feature gating

▼

3 · AI Orchestration Layer

Business Workspacedocument RAG · proposals · PII masking

Product Workspacecode · release planning · ROI · assessment

Agent OrchestratorRAG · KG · Web · Fact · Verify · Fact-Check · Latest-Check · BA/PM/Architect · ROI · Formatter/Reviewer · Image

▼

4 · Platform Services Layer

LLM ClientSASVA · AWS Bedrock

Integration Manager20+ connectors (OAuth / API keys)

Document ProcessorFastAPI :3302 · OCR · NER · classify

Email ServiceSMTP · lifecycle notifications

Report & Image GenPDF/PPTX/DOCX · Mermaid · DALL-E

Assessment PortalExternal :9000 · 28 agents

Estimation EngineExternal :8100 · Advanced estimation

▼

5 · Data & Storage Layer

Relational DBSQLite / PostgreSQL + PgBouncer

LanceDBsharded vectors (15 shards default)

Knowledge GraphJSON entity store per workspace

File System.canvas-data/tenants/{id}/

🔌 Services & Ports

Service	Port	Technology	Notes
Web App	`3300`	Next.js 14 / Node.js	`WEB_PORT` override
Mobile (Expo)	`3301`	React Native	Dev server
Document Processor	`3302`	Python FastAPI	Required for RAG indexing
PostgreSQL	`5432`	PostgreSQL	Optional (SQLite default)
Estimation Engine	`8100`	External service	Advanced estimation
Assessment Portal	`9000`	External service	Code assessment API
Pipeline Events	`5050`	Event stream	Estimation progress
Pipeline Visualizer	`5173`	Web UI	Estimation progress UI

📁 Project Structure

sasva-canvas/
├── app/api/              # 165+ API route modules
│   ├── auth/             # Login, SSO, signup, permissions
│   ├── workspace/        # Chat, stream, index, upload
│   ├── workspaces/       # CRUD, share, artifacts, comments
│   ├── operations/       # Release planning, ROI, backlog, JIRA push
│   ├── billing/          # Stripe/Braintree subscriptions
│   ├── integrations/     # OAuth start/callback (MS, Atlassian, SF)
│   ├── assessment/       # Legacy proxies (mostly 410)
│   ├── estimation/       # Advanced Estimation Engine proxy
│   ├── email/            # SMTP config & notifications
│   ├── support/          # Help Center threads
│   ├── maintenance/      # Admin maintenance tools
│   └── lifecycle/        # SDLC metrics dashboard
├── components/           # React UI (chat, workflow, settings)
├── lib/                  # Agents, integrations, LLM, billing, logging
│   ├── agents/           # 25+ agent implementations
│   ├── integrations/     # Integration manager + clients
│   ├── billing/          # Stripe/Braintree gateways
│   ├── logging/          # Structured logger (17 categories)
│   ├── telemetry/        # PostHog + gateway telemetry
│   └── privacy/          # PII redactor
├── services/document-processor/  # Python FastAPI :3302
├── desktop-app/          # Electron 33 + ctx-code
├── mobile-app/           # Expo React Native
└── .canvas-data/         # Runtime: DB, uploads, logs, shards

API Reference

165+ REST API route modules across 31 categories — authentication, workspaces, operations, billing, support, and more

Base URL: https://<deployment-host> (local: http://localhost:3300).
Auth: HTTP-only session_token cookie or Authorization: Bearer <token>.
Multi-tenant: X-Tenant-ID header when applicable.

📊 API Categories (31 · 165 routes)

Category	Routes	Key Endpoints
System & health	3	`GET /api/ping`, `GET /api/health/database`, `GET /api/runtime-config`
Authentication	11	`POST /api/auth/login`, `sso`, `signup`, `credential-key`, `permissions`, `studio-token`
Users	3	`GET+POST /api/users`, `GET+PUT+DELETE /api/users/[id]`, `POST /api/users/[id]/approve`
Tenants	3	`GET+POST /api/tenants`, `GET+PUT+DELETE /api/tenants/[id]`, `GET /api/tenants/public`
Workspaces	6	`GET+POST /api/workspaces`, share, shareable-users, extract-process-management
Workspace AI & indexing	11	`POST /api/workspace/chat/stream`, multi-agent-chat/stream, index, upload, agent-report
Chat history	3	`GET+POST /api/chat-history`, `PATCH /api/chat-history/[id]/feedback`
General chat	1	`POST /api/chat`
Documents	4	`POST /api/documents/upload`, generate, parse, fetch
Operations & planning	19	`roi-analysis/stream`, generate-usecases, breakdown-epic, estimate-effort, publish-release-plan, push-to-jira, capacity-planning
Jira	1	`POST /api/jira/release-items`
Estimation	8	`POST /api/estimation/breakdown`, sync, events, status, results
Planning drafts	4	`GET+POST /api/planning/drafts`, estimations, fetch-results
Release plans	2	`GET+POST /api/release-plans`, `GET+PUT+DELETE /api/release-plans/[id]`
Assessment	7	`POST /api/assessment/analyze` (410 deprecated), check, status, events, results
Repository	4	`POST /api/repository/clone`, clone-background, pull, upload-local
Connectors & integrations	9	OAuth start+callback (MS/Atlassian/Salesforce), `POST /api/connectors/test`
Settings & system config	4	`GET+PUT /api/settings`, system-config, database config
Email	3	`GET+PUT /api/email/config`, logs, notifications
Artifacts & collaboration	9	Artifact CRUD, comments, collaborators, versions, review workflow
Billing & payments	23	plans, subscriptions, payment-methods, invoices, webhooks, cron, reports
Knowledge chat	1	`POST /api/knowledge-chat`
AI, LLM & tools	5	`POST /api/llm/generate`, agents/generate-questions, tools/generate-file
Research	2	`POST /api/market-research`, `POST /api/research/website`
Admin & notifications	3	`GET /api/admin/metrics`, feedback, notifications
Lifecycle analytics	1	`GET /api/lifecycle/metrics`
Support	4	`GET+POST /api/support/threads`, messages, unread
Maintenance	6	cleanup, database, files, logs, reindex, migrate-tenant-data, shards
Debug	3	`GET /api/debug/env`, database, index-status
Extract ecosystem	1	`POST /api/extract-ecosystem`
Development-only	1	`POST /api/dev/test-image-extract`

🔑 Authentication Patterns

🍪
Session cookie — HTTP-only session_token (opaque server-side token, not JWT)
🔐
Bearer fallback — Authorization: Bearer <token> for API clients
🔒
Encrypted credentials — RSA-OAEP client-side encryption via GET /api/auth/credential-key
✍️
Ed25519 signing — Cryptographic permission verification on session restore
👤
Role hierarchy — Super Admin → Tenant Admin → Analyst → Viewer. 106 auth-required routes.

⚙️ Operations API Endpoints

Endpoint	Purpose
`POST /api/operations/generate-usecases`	AI use case generation for release planning
`POST /api/operations/transform-to-usecases`	Transform inputs to use cases
`POST /api/operations/breakdown-epic`	EPIC → stories breakdown
`POST /api/operations/breakdown-detailed`	Detailed story/task breakdown
`POST /api/operations/estimate-effort`	Effort estimation (SASVA or Advanced Engine)
`POST /api/operations/generate-backlog`	Generate backlog items
`POST /api/operations/roi-analysis`	Standard ROI analysis
`POST /api/operations/roi-analysis-v2`	8-factor deterministic ROI
`POST /api/operations/roi-analysis/stream`	Streaming ROI with per-item progress (SSE)
`POST /api/operations/capacity-planning`	Team capacity planning
`POST /api/operations/publish-release-plan`	Publish plan to PM tool
`POST /api/operations/push-to-jira`	Export items to JIRA
`POST /api/operations/push-backlog-items`	Push to JIRA/Aha!/Asana/Azure DevOps
`POST /api/operations/format-report`	Report formatting via Formatter agent
`GET /api/operations/tickets`	Fetch ticketing system data

⚠️ Error Response Format{ "success": false, "error": "message", "code": "ERROR_CODE", "details": {} }

Setup & Deployment

Development quick start and production deployment for Ubuntu and RHEL — SASVA Canvas 4.0.7

🚀 Development Quick Start

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env — SASVA token, SerpAPI key, integration credentials

# 3. Start all services
./sasva-canvas.sh start
# Web: http://localhost:3300 | Mobile: :3301 | Doc Processor: :3302

# 4. First login — first user becomes Super Admin
# 5. Configure Settings → AI Provider, System Config, Email

🏭 Production Deployment (8 Steps)

Install prerequisites — Node.js 18+ (v20 recommended), Python 3.11+, lsof, unzip; optionally PostgreSQL
Transfer & unzip production bundle to install path (e.g. /opt/sasva-canvas); set ownership chown -R appuser:appgroup
Set permissions — chmod +x sasva-canvas.sh
Firewall — Ubuntu: ufw allow 3300/tcp 3302/tcp; RHEL: firewall-cmd --add-port=3300/tcp --add-port=3302/tcp --permanent
Start — ./sasva-canvas.sh start; verify curl http://localhost:3300/api/ping
First login — Super Admin credentials from SASVA support (secure channel)
Configure Settings — AI Provider, tenancy, SMTP, database, Assessment Portal, telemetry, workspace types
Rotate password — Change default Super Admin password immediately

💻 Supported Platforms & Hardware

Requirement	Minimum	Recommended
CPU	4 cores	8 cores
RAM	8 GB	16 GB
Disk	40 GB free	100 GB+
Ubuntu	20.04, 22.04, 24.04	22.04 LTS
RHEL family	RHEL 8/9, Rocky, Alma, Oracle Linux 8/9	RHEL 9

🔌 Services & Ports

Service	Default Port	Override
Web App (Next.js)	`3300`	`WEB_PORT` or `PORT`
Mobile (Expo)	`3301`	—
Document Processor	`3302`	`DOC_PORT`
PostgreSQL	`5432`	Optional (SQLite default)
Estimation Engine	`8100`	Settings → Estimation
Assessment Portal	`9000`	Settings → Assessment Engine
Pipeline Events	`5050`	Estimation progress stream
Pipeline Visualizer	`5173`	Estimation UI progress

📦 Production Bundle Contents

Path	Description
`sasva-canvas.sh`	Launcher — start, stop, status, logs, restart, app-logs
`web/`	Next.js standalone production build
`doc-processor/`	Document Processor binary (Python FastAPI)
`node/`	Bundled Node.js runtime (optional)
`.canvas-data/`	Created on first run — DB, uploads, logs, tenant data
`.sasva-runtime/`	PID files, service stdout/stderr logs

Build scripts: scripts/installer/build-production-bundle-ubuntu.sh, build-production-bundle-rhel.sh. Flags: --output-dir, --skip-doc, --skip-node.

✅ Post-Install Settings Checklist

#	Setting	Default / Notes
1	My Profile	Change default Super Admin password
2	AI Provider	SASVA Config Server URL, Token, Model (`sasva-expert-model`), Embedding (`sasva-embedding-v1`)
3	System Configuration	Tenant mode (single/multi), organization name
4	Database	SQLite (evaluation) or PostgreSQL (production) + optional PgBouncer
5	Email (SMTP)	Required for password reset and lifecycle notifications
6	Assessment Portal	`http://localhost:9000` if using code assessment
7	Estimation Engine	`http://localhost:8100` for Advanced Estimation
8	Telemetry	PostHog key/host, gateway telemetry URL (optional)
9	Workspace Types	Enable per license: Market Research, Estimation, Assessment, Business, etc.
10	OAuth / SSO	Azure AD app registration, integration OAuth apps (see Security tab)

⚙️ systemd Service (Optional)

# /etc/systemd/system/sasva-canvas.service
[Unit]
Description=SASVA Canvas Platform
After=network.target

[Service]
Type=forking
User=appuser
WorkingDirectory=/opt/sasva-canvas
ExecStart=/opt/sasva-canvas/sasva-canvas.sh start
ExecStop=/opt/sasva-canvas/sasva-canvas.sh stop
Restart=on-failure

[Install]
WantedBy=multi-user.target

Configuration

Environment variables, settings files, OAuth/SSO setup, and configuration priority

🔧 Core Environment Variables

# Server
PORT=3300
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://canvas.yourcompany.com

# SASVA LLM (default provider)
LLM_PROVIDER=sasva
SASVA_SERVER_URL=https://infgw.accelerite.com
SASVA_TOKEN=your-token
SASVA_MODEL=sasva-expert-model
SASVA_EMBEDDING_MODEL=sasva-embedding-v1

# AWS Bedrock (alternative)
AWS_ACCESS_KEY_ID=AKIAXXXXX
AWS_SECRET_ACCESS_KEY=xxxxx
AWS_REGION=us-east-1
BEDROCK_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0

# Integration token encryption (required for OAuth)
INTEGRATION_TOKEN_SECRET=min-16-characters-secret

# Market Research
SERPAPI_API_KEY=xxxxx

# Logging
LOG_LEVEL=INFO
LOG_CONSOLE=true
LOG_FILE=true

🔗 OAuth & SSO Environment Variables

Provider	Variables	Scopes / Notes
Azure AD (login)	`AZURE_AD_CLIENT_ID`, `AZURE_AD_TENANT_ID`, client secret	openid, profile, email, offline_access. Redirect: `/auth/callback` or `/private/setting`
Microsoft (integrations)	`AZURE_AD_CLIENT_ID`, `AZURE_AD_TENANT_ID`	SharePoint: Sites.Read.All, Files.Read.All. Dynamics: user_impersonation
Atlassian	`ATLASSIAN_OAUTH_CLIENT_ID`, `ATLASSIAN_OAUTH_CLIENT_SECRET`	OAuth 2.0 3LO + PKCE for JIRA/Confluence
Salesforce	`SALESFORCE_OAUTH_CLIENT_ID`, `SALESFORCE_OAUTH_CLIENT_SECRET`	api, refresh_token, offline_access

OAuth callback URIs (append to public base URL): /api/integrations/microsoft/oauth/callback, /api/integrations/atlassian/oauth/callback, /api/integrations/salesforce/oauth/callback, popup completion at /auth/integration-complete.

📁 Settings Files

File	Location	Contents
`settings.json`	`.canvas-data/tenants/{id}/`	LLM provider, model, embedding, feature flags, Assessment/Estimation URLs
`database-config.json`	`.canvas-data/`	SQLite or PostgreSQL connection settings
`email-config.json`	`.canvas-data/`	SMTP host, auth, notification toggles per event
`system-config.json`	`.canvas-data/config/`	Tenant mode, org name, branding, demo workspace toggle
`billing_settings`	Database table	Stripe/Braintree gateway credentials (admin UI, not env vars)

⚙️ Configuration Priority

Tenant settings.json — highest priority per-tenant overrides
Environment variables (.env or system env)
Default configuration — built-in defaults (model: sasva-expert-model, embedding: sasva-embedding-v1, assessment: :9000, estimation: :8100)

🔌 Integration Auth Modes (per workspace connection)

Connection	OAuth Field	Auth Mode
SharePoint	`microsoftConnectionId`	`microsoft_oauth`
Confluence	`atlassianConnectionId`	`atlassian_oauth`
JIRA	`atlassianConnectionId`	`atlassian_oauth`
Dynamics	`microsoftConnectionId`	`microsoft_oauth`
Salesforce	`salesforceConnectionId`	`salesforce_oauth`
GitHub/GitLab	—	Personal access token (PAT)
Google Drive	—	Service account key JSON

Storage & Database

Data persistence, vector indexing, knowledge graph, and file storage architecture

💾 Database Options

SQLite (Default)

✅
Embedded, zero external DB config
✅
Per-tenant database files in multi-tenant mode
✅
Automatic schema creation and migrations
✅
Ideal for single-server evaluation deployments

PostgreSQL (Production)

✅
Enterprise-grade with connection pooling
✅
Optional PgBouncer (pgbouncer/ config)
✅
Tenant-scoped rows in shared database
✅
Configure via Settings → Database or database-config.json

📁 File System Layout

.canvas-data/
├── tenants/{tenantId}/
│   ├── settings.json           # Tenant LLM & feature settings
│   ├── uploads/{workspaceId}/  # Raw uploaded documents
│   └── shards/shard-{NN}/      # LanceDB vector shards
│       └── vectordb/{workspaceId}/
├── config/
│   └── system-config.json      # Platform-wide config
├── logs/                       # Structured application logs
│   ├── {category}-{date}-v{N}.log
│   ├── audit/audit-{date}.jsonl
│   └── critical/
└── database-config.json

.sasva-runtime/
├── logs/                       # Service stdout/stderr
│   ├── web-app.log
│   ├── doc-processor.log
│   └── mobile-app.log
├── data/graph/{ownerId}/{workspaceId}/  # Knowledge graph JSON
└── pids/

🔍 Vector Store (LanceDB)

Property	Value
Technology	LanceDB — sharded per tenant
Path	`.canvas-data/tenants/{tenant}/shards/shard-{NN}/vectordb/{workspaceId}/`
Embedding model	`sasva-embedding-v1` (default, via SASVA embedding server)
Chunk size	1500 chars (processor default), 1000/2000 (JS fallback)
Max chunks/workspace	50,000 (`MAX_CHUNKS_PER_WORKSPACE`)
Reindex	`POST /api/maintenance/reindex` or `POST /api/workspace/index`

🕸️ Knowledge Graph

Entity and relationship extraction via spaCy NER during document processing. Stored as JSON at .sasva-runtime/data/graph/{ownerId}/{workspaceId}/. Queried by Knowledge Graph Agent for cross-document entity resolution and relationship lookup.

📄 Document Ingestion Pipeline

Step	Details
1 · Receive	Save raw file to `uploads/{workspaceId}/`. Max 10 MB web upload, 500 MB via processor multipart.
2 · Extract	Python processor (:3302): pdfplumber, python-docx, openpyxl, python-pptx, BeautifulSoup, Tesseract OCR
3 · Classify	16+ format classifiers (financial_data, invoice, sales_pres, etc.)
4 · Handle	Specialized handlers per document type
5 · Graph	spaCy NER → entities & relationships
6 · Chunk & Embed	Intelligent chunking → SASVA embedding server
7 · Index	Store vectors in LanceDB shard for workspace

Additional index sources: SharePoint, Confluence, Google Drive, GitHub, CRM, tickets, Slack, websites — via workspace connection slots and POST /api/workspace/index.

Security

Authentication, authorization, data protection, and connector security — enterprise-grade by design

🔐 Authentication Methods

Method	Implementation	Details
Email / Password	`POST /api/auth/login`	RSA-OAEP client-side encryption via `GET /api/auth/credential-key`. Signup requires admin approval.
Azure AD SSO	MSAL + PKCE	Scopes: openid, profile, email, offline_access. Server validates ID token. Desktop uses Electron safeStorage.
Session	HTTP-only cookie	Opaque `session_token` (not JWT). Bearer fallback for API clients. Configurable timeout/idle extension.
Password Reset	Email token flow	`POST /api/auth/forgot-password`, `POST /api/auth/reset-password`
Studio Token	`POST /api/auth/studio-token`	Embedded app authentication
Account Lockout	Rate limiter	Failed attempt tracking with lockout period

👥 Role-Based Access Control

Role	Scope	Capabilities
Super Admin	Platform-wide	All tenants, system config, maintenance, destructive ops, billing admin, cross-tenant support
Tenant Admin	Single tenant	User management, AI provider, integrations, email config, tenant settings, feedback review
Analyst	Own + shared	Create/manage workspaces, run operations, share workspaces, chat
Viewer	Shared only	Read-only access to shared workspaces and artifacts

Workspace sharing permissions: Viewer (read), Editor (read + operate), Admin (full control including sharing). Ed25519 cryptographic signing on permissions and session restore. HMAC signature on auth endpoints.

🔒 Data Protection

Feature	Implementation	Details
PII Masking	`pii-redactor.ts`	Query-time redaction: EMAIL, PHONE, SSN, PAN, Aadhaar, CREDIT_CARD, IP, PERSON. Business workspace chat (default ON).
Credential Masking	`workspace-credential-mask.ts`	API responses show `••••••••` for stored secrets
OAuth Token Storage	Server-side encrypted stores	Tokens never in workspace JSON. `INTEGRATION_TOKEN_SECRET` (≥16 chars).
Encryption at Rest	Electron safeStorage	Desktop credential encryption. AES-256-GCM for billing card tokens.
Tenant Isolation	Per-tenant DB/files/logs	Multi-tenant mode scopes all data by tenantId
Upload Validation	`upload-validation.ts`	File type, size limits (default 10 MB web, 500 MB processor)
Email Domain Validation	`email-domain-validator.ts`	Tenant email domain restrictions
Audit Logging	AUDIT level	PII_MASKED events, sensitive operations in `audit/*.jsonl`
Report Signing	Ed25519	Cryptographic report signing with client-side verification

🔗 Integration OAuth & SSO

Two auth layers: (1) User session — Microsoft Entra via MSAL; (2) Integration OAuth — popup to Microsoft/Atlassian/Salesforce → encrypted refresh tokens per tenant/user.

Provider	OAuth Start	Use Cases	Legacy Fallback
Microsoft Entra	`/api/integrations/microsoft/oauth/start`	SharePoint (`Sites.Read.All`, `Files.Read.All`), Dynamics (`user_impersonation`)	Client credentials
Atlassian	`/api/integrations/atlassian/oauth/start`	JIRA Cloud, Confluence (OAuth 2.0 3LO + PKCE)	Email + API token
Salesforce	`/api/integrations/salesforce/oauth/start`	CRM delegated OAuth (`api refresh_token offline_access`)	Password grant

Required: NEXT_PUBLIC_APP_URL (exact origin, no trailing slash). Callback URIs: /api/integrations/{provider}/oauth/callback, popup completion at /auth/integration-complete.

🛡️ AI Transparency & Responsible Use

📋
Input disclaimer — shown before first chat message in workspace
🏷️
AI-generated labels — on operation results and generated documents
📄
Artifact review workflow — draft → in_review → changes_requested → approved before download
📖
Responsible Use page — AI limitations and appropriate use guidance

CLI Tools & Service Manager

sasva-canvas.sh — unified launcher for development and production deployments

🚀 Service Manager Commands

Command	Description
`./sasva-canvas.sh start [web\|mobile\|doc]`	Start services (all or specific). Web :3300, Mobile :3301, Doc :3302
`./sasva-canvas.sh stop [web\|mobile\|doc]`	Stop services
`./sasva-canvas.sh restart`	Restart all services
`./sasva-canvas.sh status`	Service status and URLs
`./sasva-canvas.sh logs [web\|mobile\|doc]`	Last 50 lines of runtime log
`./sasva-canvas.sh logs-f [web\|mobile\|doc]`	Follow runtime logs in real-time
`./sasva-canvas.sh app-logs [category] [lines]`	Structured application logs (e.g. `app-logs api 100`)
`./sasva-canvas.sh app-logs-f [category]`	Follow structured logs (e.g. `app-logs-f auth`)
`./sasva-canvas.sh app-logs`	List all application log files

🔧 Utility Scripts

Script	Purpose
`scripts/installer/build-production-bundle-ubuntu.sh`	Build air-gapped Ubuntu production bundle
`scripts/installer/build-production-bundle-rhel.sh`	Build air-gapped RHEL production bundle
`scripts/migrate-shards.ts`	LanceDB shard migration
`scripts/test-pii-redactor.ts`	PII redaction testing
`scripts/load-tests/*`	Load testing (auth, chat, planning, file upload)
`scripts/sasva-canvas-bundle.sh`	Bundle launcher wrapper
`restart-server.sh`	Quick dev server restart

🤖 ctx-code / SASVA Native CLI

Verify, Fact-Check, and Latest-Check agents run via ctx-code CLI. Configured in Settings → AI Runtime with scopes: canvas, estimation, assessment. Desktop app bundles platform-specific binaries in desktop-app/ctx-code/. Project-level overlay via cli.json.

📦 Production Bundle Flags

./build-production-bundle-ubuntu.sh --output-dir /path/to/output
  --skip-doc     # Skip document processor binary
  --skip-node    # Skip bundled Node.js runtime

Desktop Application

Native desktop experience — Electron 33 with full web UI parity and Azure AD SSO

🖥️

Electron 33 + electron-vite

Cross-platform desktop app (macOS DMG, Windows EXE, Linux AppImage) via electron-builder.yml.

🔐

Azure AD SSO (PKCE)

Native MSAL flow with Electron safeStorage for credential encryption. @azure/msal-browser integration.

🌐

Full Web UI Parity

All web workflows: release planning, ROI, assessments, lifecycle dashboard, billing, settings, artifact review, plan selection.

⚡

Fast-Path Queries

Casual messages bypass full RAG pipeline for instant responses.

🎯 Desktop Features

Feature	Details
Bundled ctx-code	Platform-specific CLI binaries in `resources/` for Verify/Fact-Check agents
OS notifications	Electron `Notification` API for operation completion
Native file dialogs	Open/save via IPC handlers
Connection status	Backend connectivity indicator in UI
Keyboard shortcuts	`useKeyboardShortcuts` hook
Views	Workspaces, all operation flows, settings, metrics, user-feedback, help, lifecycle, artifact-review, plan-selection

📦 Build Commands

cd desktop-app
# Bundle ctx-code into desktop-app/ctx-code/ first
npm run dev              # Development
npm run package          # All platforms
npm run package:mac      # macOS DMG
npm run package:win      # Windows EXE
npm run package:linux    # Linux AppImage

Mobile Application

React Native / Expo app for iOS and Android — business workspace focus with AI chat

📱

Platforms

iOS and Android via EAS cloud builds (dev/preview/production profiles).

💼

Business Workspaces

Create, list, and manage Business workspaces with full document access.

💬

AI Chat

RAG-powered multi-agent chat with SSE streaming and Extended Thinking.

🎤

Voice Dictation

Speech-to-text via useVoiceRecording hook.

🎯 Mobile Features

Feature	Details
Authentication	Email/password + Microsoft SSO
Document access	Connected document sources and uploaded files
Extended Thinking	Visible reasoning blocks in chat
Dark mode	Supported
PostHog telemetry	Optional analytics (disabled by default)
Secure storage	Expo Secure Store for tokens
Real-time sync	Same backend APIs as web (:3300)
State management	Zustand + Expo Router navigation

Not in mobile (by design): Product workspace full parity, release planning workflows, desktop-only admin tools.

🚀 Development & Build

cd mobile-app
npm install

# Configure API in constants/app-config.ts
# iOS Simulator: http://localhost:3300
# Android Emulator: http://10.0.2.2:3300
# Physical device: http://YOUR_IP:3300

npm start                # Expo dev server (:3301)
npm run ios              # iOS Simulator
npm run android          # Android Emulator

# Production builds
npm install -g eas-cli
eas login
eas build --platform ios
eas build --platform android

📦 Tech Stack

Technology	Purpose
React Native	Cross-platform mobile framework
Expo SDK 51	Development platform & build tools
Expo Router	File-based navigation
Zustand	State management
Expo Secure Store	Secure token storage

Code & Process Assessment

Deep intelligence from source code to strategy — Assessment Portal with 28 specialized agents and 10-phase pipeline

Architecture: Canvas frontend calls Assessment Portal directly (default http://localhost:9000). Canvas proxy routes (POST /api/assessment/analyze) return 410 Deprecated. Configure portal URL in Settings → Assessment Engine.

🔬 Capability Groups

💻

Code & Developer Intelligence

Cyclomatic complexity, hotspot detection, AI-powered PR review, developer profiling, commit velocity, sprint cadence, throughput analysis.

🛡️

Security & Compliance

CVE scanning across dependencies/containers, SAST anti-pattern detection, SBOM generation, license compliance, supply chain risk assessment.

📈

Market & Org Intelligence

Competitive landscape analysis, org sentiment, geographic team distribution, reputation indicators, developer health metrics.

🤖

AI Synthesis & Reporting

Cross-concern impact assessment, strategic recommendations, product classification, portfolio reporting across repositories.

⚙️ 10-Phase Assessment Pipeline

Phase	Name	Tasks	Mode	Agents
1	Repository Setup	2	Sequential	Clone, validate, index
2	Code Analysis	2	Parallel	Complexity, hotspots
3	Security Analysis	3	Parallel	CVE, SAST, SBOM
4	AI Analysis	1	Parallel	AI-powered code review
5	Developer & Impact	2	Parallel	Profiling, velocity
6	Product Classification	1	Sequential	Stack categorization
7	Project Aggregation	10	Parallel	Cross-repo metrics
8	Insight Synthesis	2	Parallel	Strategic recommendations
9	Deep Research	2	Sequential	Market/org intelligence
10	Reporting	3	Sequential	HTML/PDF portfolio reports

28 specialized agents orchestrated via dependency-driven DAG for maximum parallel throughput. Multi-provider LLM for code review and research.

🔗 Assessment Portal API (Frontend → Portal)

Endpoint	Purpose
`POST /api/v2/analyze`	Start analysis job
`GET /api/v2/assessment/check/{repoName}`	Check existing assessment
`GET /api/v2/jobs/{jobId}`	Job status
`GET /api/v2/jobs/{jobId}/pipeline-token`	Pipeline visualizer token
`GET /api/v2/monitor/events`	Real-time SSE events
`GET /api/v2/monitor/pipeline/{repoName}`	Pipeline progress
`GET /api/repositories/{repoId}/insights`	Legacy insights
`/workspace/results/{repoId}/{repoId}_assessment_report.html`	HTML assessment report

📊 Analysis Types & UI Modes

Analysis Types

📊
ext_codeQualityAnalysis — complexity distribution
🛡️
ext_vulnerabilityAnalysis — dependency CVEs
🔍
ext_sastAnalysis — static security testing
🔧
ext_techStack — technology detection
🔥
int_hotspotAnalysis — code hotspots
📈
int_functionComplexityAnalysis — function-level
📜
int_repositoryHistoryAnalysis — git history
🏷️
int_commitClassificationAnalysis — commit types

Code Assessment UI Modes

💻
Code — technical debt & quality themes
🛡️
Security — vulnerability/SAST review
🔬
Full — comprehensive combined scan

Repository input: remote Git URL (POST /api/repository/clone), background clone with polling, or local upload (POST /api/repository/upload-local).

Observability & Logging

Structured logging, telemetry, admin dashboards, and diagnostic tooling — production-grade observability for on-premise deployments

📊 Log Severity Levels

Level	Priority	Use
DEBUG	0	Development tracing, verbose diagnostics
INFO	1	Normal operational messages
WARN	2	Degraded conditions, retries
ERROR	3	Failed operations
CRITICAL	4	System-critical failures (dedicated critical log)
AUDIT	5	Security/compliance — always recorded regardless of LOG_LEVEL

Environment: LOG_LEVEL (DEBUG dev / INFO prod), LOG_CONSOLE, LOG_FILE, LOG_COLORS

📂 Log Categories (17)

Category	Typical Contents
`api`	HTTP requests, responses, status codes, latency
`product-ws`	Release planning, ROI, backlog, estimation operations
`business-ws`	Proposals, presentations, business analysis operations
`workspace`	Indexing, RAG queries, document processing triggers
`chat`	Chat sessions, streaming events, conversation lifecycle
`agents`	Multi-agent orchestration, verify/fact-check rounds
`auth`	Login, SSO, session, permission checks, lockouts
`integrations`	OAuth flows, connector tests, SASVA/Estimation/Assessment/SerpAPI calls
`documents`	Upload, parse, classify, chunk, embed pipeline
`database`	DB queries, migrations, vacuum, health checks
`settings`	Configuration changes, tenant settings updates
`users`	User CRUD, approval workflow, role changes
`tenants`	Tenant provisioning, isolation events
`cache`	Cache hits/misses, invalidation
`performance`	Timing, throughput, resource metrics
`security`	PII masking events, credential access, rate limiting
`system`	Startup, shutdown, service health, maintenance

📁 Log Locations & Retention

Type	Path	Notes
Runtime stdout	`.sasva-runtime/logs/web-app.log`	Next.js process output
Doc processor	`.sasva-runtime/logs/doc-processor.log`	Python FastAPI service
Mobile	`.sasva-runtime/logs/mobile-app.log`	Expo dev server
Structured app logs	`.canvas-data/logs/{category}-{date}-v{N}.log`	Per-category rotating files
Tenant-scoped	`.canvas-data/logs/tenants/{tenantId}/`	Multi-tenant isolation
Audit trail	`.canvas-data/logs/audit/audit-{date}.jsonl`	JSON Lines compliance log
Critical events	`.canvas-data/logs/critical/`	CRITICAL-level dedicated logs

Rotation: 5 MB or daily; 10 files per category (~50 MB cap). Gzip on service restart. Format: [TIMESTAMP] [LEVEL] [CATEGORY] [T:tenant] [U:user] [ACTION] MESSAGE | Meta: {...} | Duration: Nms

Logging and Monitoring Stack Enablement and Customer Responsibility

Purpose

The Logging and Monitoring Stack is provided as an optional operational capability to enhance observability, monitoring, troubleshooting, and operational reporting for the SASVA platform components, including Canvas and IDE deployments. This capability is not a mandatory prerequisite for the deployment or operation of the core SASVA product stack.

Customer Opt-In Requirement

Implementation and enablement of the Logging and Monitoring Stack within the customer environment shall be performed only upon the customer’s explicit decision to adopt the solution. The deployment of monitoring components, including but not limited to Prometheus, Grafana, Loki, Node Exporter, and/or Grafana Alloy, is considered an optional infrastructure enhancement beyond standard SASVA product deployment.

Customers may choose to:

Enable the complete Logging and Monitoring Stack.
Enable selected monitoring components based on their operational requirements.
Operate the SASVA platform without the optional Logging and Monitoring Stack.

The decision to implement or not implement this capability remains solely with the customer.

Infrastructure Dependency and Provisioning Responsibility

The Logging and Monitoring Stack requires dedicated infrastructure resources in addition to the resources allocated for the core SASVA platform components.

The customer is responsible for provisioning and maintaining the required infrastructure resources, including but not limited to:

Virtual Machines (VMs) or equivalent compute resources.
CPU, memory, and storage capacity.
Network connectivity and firewall configurations.
Backup and retention storage (if applicable).
Operating system and platform prerequisites.
High availability and disaster recovery configurations (where required).

Infrastructure sizing requirements may vary depending on factors such as:

Number of application instances being monitored.
Log generation volume.
Metrics collection frequency.
Data retention requirements.
Availability and performance objectives.

Ownership and Operational Responsibility

Where the Logging and Monitoring Stack is enabled, operational ownership of the underlying infrastructure remains with the customer unless otherwise agreed through a separate managed services engagement.

The customer is responsible for ensuring that adequate infrastructure capacity is available to support:

Metrics collection and retention.
Log ingestion and retention.
Dashboard visualization and reporting.
User access management and authentication.
Ongoing operational monitoring of the monitoring platform itself.

Summary

For audit and governance purposes, it is important to note that:

The Logging and Monitoring Stack is an optional add-on capability and is not part of the mandatory SASVA product deployment baseline.
Non-deployment of the Logging and Monitoring Stack by the customer does not constitute product deficiency or non-compliance of the SASVA platform.
Any limitations in monitoring, observability, alerting, log retention, troubleshooting visibility, or operational reporting resulting from the customer’s decision not to implement the Logging and Monitoring Stack shall be outside the scope of the SASVA product responsibilities.
The customer acknowledges that implementation of the Logging and Monitoring Stack requires additional infrastructure resources and associated operational support.

📡 Telemetry & Analytics

PostHog Analytics

Settings → Telemetry. ~40 named events: auth, workspace, chat, documents, integrations, errors. Session recording and autocapture disabled by default.

Gateway Telemetry

SDLC task telemetry spec v1.3 — async to external gateway. Token counts, timing, agent rounds, workspace context. Never blocks core workflows.

Platform Metrics

GET /api/admin/metrics — users, workspaces, conversations, DB stats, LLM token usage, billing summary.

Lifecycle Analytics

GET /api/lifecycle/metrics — SDLC phase mapping, operation/agent usage, backlog breakdown. Time ranges: 7d, 30d, 90d, all.

🔧 CLI & Debug Commands

# Runtime service logs
./sasva-canvas.sh logs              # All services (last 50 lines)
./sasva-canvas.sh logs web          # Web app only
./sasva-canvas.sh logs-f            # Follow in real-time

# Structured application logs
./sasva-canvas.sh app-logs          # List all log files
./sasva-canvas.sh app-logs api 100  # Last 100 API log lines
./sasva-canvas.sh app-logs-f auth   # Follow auth logs

# Admin maintenance
GET  /api/maintenance/logs          # Log viewer (admin UI)
GET  /api/debug/env                 # Environment diagnostics
GET  /api/debug/index-status        # Vector index health
GET  /api/ping                      # Liveness check
GET  /api/health/database           # DB health

🔍 Debug Quick Reference

Investigate	Log Category
HTTP/API errors	`api-*.log`
Release planning, ROI, backlog	`product-ws-*.log`
Proposals, business ops	`business-ws-*.log`
SASVA, Estimation, Assessment, SerpAPI	`integrations-*.log`
Login, SSO, sessions	`auth-*.log`
Indexing, RAG retrieval	`workspace-.log`, `chat-.log`
Multi-agent pipeline	`agents-*.log`
Compliance audit	`audit/audit-*.jsonl`
Service crashes	`.sasva-runtime/logs/*.log`

Email Notifications & User Feedback

Lifecycle email notifications, in-chat feedback, Help Center support threads, and in-app collaboration notifications

📧 Email Configuration

Configure in Settings → Email (Super Admin / Tenant Admin).

Setting	Options / Details
SMTP Presets	Gmail, Outlook/Office 365, SendGrid, Mailgun, Amazon SES, Custom
Auth types	none, plain, login, oauth2 (XOAUTH2)
TLS	Port 465 (implicit TLS) or 587/25 (STARTTLS)
Rate limiting	Configurable max/hour (default 100) and max/day (default 1000)
Global kill switch	`notifications.enabled` — disable all outbound email
Audit log	Last 1000 sends; view via `GET /api/email/logs`
APIs	`GET+PUT /api/email/config`, `POST /api/email/notifications`, `POST /api/billing/email/send`

🔔 Notification Categories (Toggleable Per Event)

Category	Events	Recipients
User / Account	Welcome, pending approval, approved, deactivated, password reset/changed, account locked, admin approval notice	User + tenant admins
System	System alerts, maintenance notices	Admins
Workspace	Created, updated, deleted, shared/invitation, source added	Owner / invitee; admins on create/delete; collaborators BCC on source added
Operations	Started, completed, failed	Operator; collaborators BCC on completed

Operation emails triggered for: Market Research, ROI Analysis, Generate Backlog, Publish Release Plan, and Breakdown Estimations.

👍 In-Chat Feedback

✅
Thumbs up/down on assistant messages in workspace chat
✅
API — POST /api/chat-history/[id]/feedback (values: positive, negative, null)
✅
Admin console — Header → User Feedback; filters by rating, workspace, user, date range
✅
CSV export — GET /api/admin/feedback with enriched user/workspace context

💬 Help Center & Support Threads

Feature	Details
Create thread	Help Center → Contact Support. Categories: feedback, suggestion, issue, question, other
Status workflow	open → in_progress → resolved → closed
Messages	`GET+POST /api/support/threads/[id]/messages`
Unread badge	`GET /api/support/unread` in app header
Staff inbox	Tenant admins see tenant threads; super admins see cross-tenant with `scope=admin`

Support SLAs for customer-reported issues

These SLAs apply to issues that Canvas users raise to the platform support team (email, Help Center → Contact Support, or the support channel). Support files a ticket for each request. All targets are expressed in hours. They do not apply to security-finding remediation or to other internal operational SLAs.

Priority is set when the ticket is triaged: Urgent, High, Normal, or Low. A target of 0h means no SLA is committed for that metric at that priority.

Reply metrics — how quickly we respond to a customer’s request.

SLA target	Urgent	High	Normal	Low
First reply time	0.5h	2h	4h	8h
Next reply time	1h	12h	48h	0h

Update metrics — how frequently we keep customers updated.

SLA target	Urgent	High	Normal	Low
Pausable update	12h	45h	84h	0h

Resolution metrics — how long we should take to solve a request.

SLA target	Urgent	High	Normal	Low
Requester wait time	96h	384h	1080h	0h

🔔 In-App Notifications (Artifacts)

Collaboration notifications for artifact comments, shares, and approval requests.

✅
GET+PUT /api/notifications — list, mark read, mark all read
✅
Stored in artifact_notifications table with unread count in header

Administration & Platform Management

Super Admin and Tenant Admin tools — users, tenants, billing, maintenance, privacy

👥 User & Tenant Management

✅
User approval workflow — New signups require admin approval; first registrant becomes Super Admin. POST /api/users/[id]/approve
✅
4 roles — Super Admin, Tenant Admin, Analyst, Viewer with server-side RBAC enforcement and Ed25519 permission signing
✅
Multi-tenant mode — Single-tenant or multi-tenant; per-tenant data isolation; configurable email domain. GET+POST /api/tenants
✅
Tenant settings — Per-tenant settings.json overrides for LLM, features, branding
✅
Demo workspaces — Pre-configured Product/Business showcase instances; toggle in Settings → Demo Workspaces

💳 Billing Plans & Entitlements

Stripe and Braintree payment gateways — hot-swappable via admin UI. Gateway credentials stored in billing_settings table (not env vars). AES-256-GCM card tokenization; 3D Secure / SCA for Stripe.

Plan	Tier	Price	Users	Workspaces	Key Features
Free	0	$0/mo	1	1	Product workspace, release planning, market analysis — no Business, no integrations
Starter	1	$29/mo	5	5	+ ROI, code assessment, JIRA & GitHub — no Business workspace
Professional	2	$79/mo	20	20	+ Business workspace, CRM, proposals, presentations, advanced estimation — no SSO
Enterprise	3	$199/mo	Unlimited	Unlimited	All features, SSO, all integrations, priority support, custom branding

Feature Key	Free	Starter	Pro	Enterprise
product_workspace	✓	✓	✓	✓
business_workspace	✗	✗	✓	✓
release_planning	✓	✓	✓	✓
roi_analysis	✗	✓	✓	✓
code_assessment	✗	✓	✓	✓
create_proposal	✗	✗	✓	✓
advanced_estimation	✗	✗	✓	✓
jira_integration	✗	✓	✓	✓
github_integration	✗	✓	✓	✓
crm_integration	✗	✗	✓	✓
sso_access	✗	✗	✗	✓
workspace_sharing	✗	✓	✓	✓

24 feature keys total. Billing APIs: /api/billing/plans, subscriptions, payment-methods, invoices, webhooks/stripe, webhooks/braintree, cron/process, reports. Subscription statuses: Active, Trial, Past Due (7-day grace), Cancelled. Dunning service for failed payments.

🔧 Maintenance Tools (Super Admin)

Tool	API	Purpose
Cleanup	`POST /api/maintenance/cleanup`	Bulk delete users, workspaces, indexes, uploads; complete reset
Database	`GET+PUT+DELETE /api/maintenance/database`	DB health, vacuum, reindex, analyze, query viewer
Files	`GET+PUT+DELETE /api/maintenance/files`	Data directory file browser
Logs	`GET+DELETE /api/maintenance/logs`	Structured log viewer and purge
Reindex	`GET+POST /api/maintenance/reindex`	Vector index rebuild across workspaces
Tenant migration	`GET+POST /api/maintenance/migrate-tenant-data`	Migrate tenant data between shards
Shards	`GET /api/maintenance/shards`	LanceDB shard management

🤝 Collaboration & Artifacts

Feature	API
Artifact CRUD	`/api/workspaces/[id]/artifacts`
Inline comments	`.../artifacts/[id]/comments`
Collaborators	`.../artifacts/[id]/collaborators`
Version history	`.../artifacts/[id]/versions`
Workspace sharing	`POST /api/workspaces/[id]/share` — email + permission (viewer/editor/admin)
In-app notifications	`GET+PUT /api/notifications` — artifact comments, shares, approvals

📄 Document Processor Service

Python FastAPI on port 3302 — required for document upload and RAG indexing.

# Supported formats
XLSX, XLS, DOCX, DOC, PPTX, PPT, PDF, HTML, JSON, MD, CSV, TSV, TXT
Images: PNG, JPG, JPEG, GIF, WEBP, BMP, TIFF (Tesseract OCR + vision fallback)

# Pipeline
Extract → Classify (16+ format classifiers) → Specialized handlers →
Knowledge graph (spaCy NER) → Chunk (1500 chars default) & embed → LanceDB indexing

# APIs
GET  /health
POST /process          # Base64 JSON (<20 MB)
POST /process/upload   # Multipart (up to 500 MB)
POST /extract

SASVA Canvas — Product Guide

Capabilities, architecture overview, and product feature reference for SASVA Canvas.

SASVA Canvas

What is SASVA Canvas?

Enterprise Connectivity

Security & Compliance

Workspaces

Multi-Agent RAG

📋 Complete Platform Capabilities

Workspace Types

Product Workspace

Business Workspace

📋 Feature Comparison

🔗 Connection Slot Reference

🚀 Workspace Lifecycle

AI Agents

📚 Chat, Retrieval & Verification Agents

💻 Product Development Role Agents

💼 Business Workspace Agents

📊 Analysis, Formatting & Output Agents

Report Generation Agent

Formatter Agent

Reviewer Agent

Image Generation Agent

⚙️ CLI-Backed Verification (ctx-code)

Ecosystem Integrations

📋 Integration Catalog

🔐 OAuth 2.0 Connectors (Recommended)

📂 Workspace Connection Slots

🔧 Integration Manager Classes

📤 Push-Back & Data Extraction

Operations

💻 Product Workspace Operations

💼 Business Workspace Operations

🔄 Extended Capabilities

🚀 Release Planning Flow (5 Steps)

1 · Use Cases

2 · EPIC / Story Breakdown

3 · Estimate

4 · Assign

5 · Publish

💰 ROI Analysis — 8 Factors

Chat & Collaboration

💬 Chat Endpoints

🧠 Intelligence Features

Extended Thinking

Source Citations

Fast-Path Queries

Stop Generation

PII Masking

Image & OCR

Voice Dictation

Inline URL Analysis

Web Search Tool

File Generation

📜 Chat History, Indexing & Reports

📡 SSE Event Types

System Architecture

🏗️ Five Architecture Layers

🔌 Services & Ports

📁 Project Structure

API Reference

📊 API Categories (31 · 165 routes)

🔑 Authentication Patterns

⚙️ Operations API Endpoints

⚠️ Error Response Format

Setup & Deployment

🚀 Development Quick Start

🏭 Production Deployment (8 Steps)

💻 Supported Platforms & Hardware

🔌 Services & Ports

📦 Production Bundle Contents

✅ Post-Install Settings Checklist

⚙️ systemd Service (Optional)

Configuration

🔧 Core Environment Variables

🔗 OAuth & SSO Environment Variables

📁 Settings Files

⚙️ Configuration Priority

🔌 Integration Auth Modes (per workspace connection)