Tech Stack

Tech Stack (ConversionIQ MVP v2)

This document captures both the current implemented tech stack in ciq-mvp2-app and the target architecture guidance for ConversionIQ MVP v2.

Constraints:

• Frontend design system is based on shadcn/ui.
• This document is architecture guidance; it does not modify implementation.

References:

• Platform principles: Platform Overview (ConversionIQ MVP)
• Layers: Architecture Layers
• Permissions: Roles & Permissions Model
• Security & compliance: Security & Compliance
• Analytics: Analytics Events (MVP)

---

0) Current implementation (codebase source of truth: ciq-mvp2-app/)

Framework

• Next.js: 16.1.6
• React / React DOM: 19.2.3
• Routing: App Router (ciq-mvp2-app/src/app/)
  • Page routes: src/app/**/page.tsx
  • Layouts: src/app/**/layout.tsx
  • Not found: src/app/not-found.tsx
  • Route handlers (API): src/app/api/**/route.ts (e.g. src/app/api/setup-status/route.ts)
• Turbopack:
  • Not explicitly enabled in scripts (dev uses next dev, not next dev --turbopack).
  • No Turbopack-specific config is present in next.config.ts.

Language

• TypeScript: 5.9.3 (resolved in package-lock.json; package.json pins typescript: ^5)
• tsconfig.json highlights:
  • strict: true
  • moduleResolution: "bundler"
  • jsx: "react-jsx"
  • Path alias: @/* → ./src/*
  • Next.js TS plugin enabled ({"name": "next"})

Styling

• Tailwind CSS: 4.2.1
  • Tailwind config: tailwind.config.ts (notably darkMode: "class", content: ["./src/**/*.{js,ts,jsx,tsx,mdx}"])
  • CSS-first Tailwind v4 setup in src/app/globals.css via:
    • @import "tailwindcss";
    • @custom-variant dark (&:is(.dark *));
• Animation utilities: tw-animate-css 1.4.0 imported in src/app/globals.css via @import "tw-animate-css";
• PostCSS: configured via postcss.config.mjs using @tailwindcss/postcss 4.2.1

Icons

• Material Symbols (Outlined) is loaded as a web font in src/app/layout.tsx:
  • <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:..." />
• Usage convention:
  • Render an icon with a <span> using the material-symbols-outlined class and the icon name as text content, e.g. cards_star.
  • Where needed, tune appearance using fontVariationSettings (e.g. "'FILL' 0, 'GRAD' 0") and fontSize.

Fonts

• Geist + Geist Mono are used via next/font/google in src/app/layout.tsx:
  • Geist({ variable: "--font-geist-sans" })
  • Geist_Mono({ variable: "--font-geist-mono" })
• CSS variables wiring:
  • globals.css maps --font-sans / --font-mono to Geist variables and applies font-family: var(--font-sans) to body.
• Inter:
  • Some UI uses an explicit inline fallback (fontFamily: "Inter, sans-serif"), but Geist is the primary app font.

UI utilities / component primitives

• Classname utility: cn() in src/lib/utils.ts
  • Built from clsx + tailwind-merge.
• shadcn/ui configuration: components.json
  • rsc: true, tsx: true, style: "radix-nova"
  • aliases: @/components, @/components/ui, @/lib/utils, etc.
  • iconLibrary: "material-symbols"
• UI building blocks in dependencies:
  • @radix-ui/react-slot (Radix primitive)
  • class-variance-authority (variant patterns; used by shadcn-style components)

Dev tooling

• ESLint: 9.39.3
  • Config style: flat config (eslint.config.mjs)
  • Extends Next.js presets: eslint-config-next/core-web-vitals and eslint-config-next/typescript
• Prettier:
  • Not currently present in package.json devDependencies.

Package manager

• npm
  • Lockfile present: ciq-mvp2-app/package-lock.json
  • App README examples use npm install / npm run dev.

---

1) Platform overview

ConversionIQ is an enterprise AI engagement platform that centralizes and governs customer interactions across channels and applications.

Platform invariants:

• Multi-workspace architecture: organizations may contain many workspaces (brands/business units).
• Knowledge-base-driven AI logic: AI outputs must be constrained by approved KB facts/tone/compliance.
• Workspace isolation is core: actions and data are scoped by org_id and workspace_id.

---

2) Frontend stack

Framework

• Next.js (App Router)
  • Default rendering model should favor Server Components where appropriate (MVP pragmatism).

Language

• TypeScript

Design system

• shadcn/ui
  • Composable components built on accessible primitives (Radix UI patterns).

Styling

• Tailwind CSS
  • Tokenized, utility-first styling aligned with shadcn/ui conventions.

Component philosophy

• Composable: small, reusable components that can be assembled into complex surfaces.
• Accessible by default: keyboard support, focus management, semantic structure.
• Headless primitives first: behavior separated from styling; themes are layered on top.

State management strategy (MVP-safe)

Use the smallest approach that preserves correctness and auditability:

• Server state:
  • Prefer framework-native data fetching and caching patterns.
  • Where client revalidation is required, use a dedicated server-state library (TBD).
• Client/UI state:
  • Keep local state inside the component where possible.
  • Use a lightweight store for cross-component UI state only when needed (TBD).

Principle: avoid introducing multiple state paradigms for the same concern.

Routing strategy

• App Router route segments mirror the product sitemap.
• Route-level docs remain the source of truth: docs/routes/**.

Icon system

• Material Symbols
  • Use a consistent subset and sizing rules across surfaces.

---

3) Backend stack

Architecture style (MVP)

• Modular monolith
  • Domain modules with explicit boundaries (Workspaces, Knowledge Bases, Channels, Apps, Billing, Audit).
  • Shared infrastructure (auth, logging, persistence) is centralized but access-controlled.

API type (MVP recommendation)

Recommended default: REST.

Rationale (MVP-safe):

• Clear boundary between frontend and domain services.
• Works cleanly across future clients and integrations.
• Easier to attach enterprise controls (authz, audit, rate limits) consistently.

If the platform is intentionally TypeScript-only end-to-end, tRPC can be considered; adopt only if:

• access control and audit hooks are enforced in a centralized layer, and
• API contract changes remain reviewable and versioned (TBD).

Domain separation principles

• Domain rules live in domain modules (and are documented in docs/domains/**).
• Route composition is a frontend concern (documented in docs/routes/**).
• Cross-cutting enforcement (authz, audit, rate limiting) must not be duplicated per route.

Authentication strategy (enterprise baseline)

Target properties:

• Session-based authentication with secure cookie handling (recommended baseline).
• Support for enterprise SSO readiness (SAML/OIDC) without redesign (future).

Implementation details are TBD and must not be assumed without confirmation.

Multi-tenant scoping

Every request must carry and enforce:

• org_id (organization scope)
• workspace_id (workspace scope) where applicable

Enforcement is strict:

• validate scope + permission on every sensitive operation
• prevent cross-workspace aggregation unless explicitly authorized and documented

---

4) Data layer

Database

MVP recommendation: a relational database (e.g., PostgreSQL) with a typed access layer.

Exact provider/ORM is TBD (must match the implementation repo).

Schema scoping strategy

• Primary scoping fields: org_id, workspace_id
• Prefer explicit scoping columns over implicit context.
• Consider row-level security only if it is fully enforced and testable (future).

Audit logging (enterprise requirement)

Store append-only audit entries for:

• auth events
• IAM changes (users/roles/permissions)
• channel connect/disconnect
• KB edit/publish
• automation/policy changes
• billing changes

Reference: Security & Compliance

Event model

MVP approach:

• Define clear domain event names and payload guidelines.
• Prefer an outbox-style pattern only if/when async processing becomes required (TBD).

Reference: Analytics Events (MVP) (analytics conventions)

Caching approach (if needed for MVP)

• Prefer framework-native caching for reads where safe.
• Add a shared cache only for verified bottlenecks (TBD).

---

5) AI layer

LLM provider strategy abstraction

• Introduce a provider interface that supports:
  • multiple providers (current and future)
  • consistent rate limiting and error handling
  • request/response redaction for logs (no PII leakage)

Provider choice is TBD.

Prompt management model

Minimum requirements:

• versioned prompts and system instructions
• workspace-scoped policy overlays (tone/compliance)
• change auditability for prompts and policies

Knowledge base resolution engine

Responsibilities:

• resolve relevant KB content for a task without cross-workspace leakage
• enforce the publish boundary (prefer published KB content)
• apply policy constraints (disallowed claims, required disclaimers)

Inheritance logic enforcement

The AI layer must enforce precedence rules for constraints and configuration (example categories):

• org-level policies → workspace-level policies → KB-level constraints

Exact inheritance sources and precedence are TBD and must be documented in domain/architecture docs when confirmed.

Safeguards and rate limits

Enterprise baseline:

• strict outbound action gating (permissions + optional approvals)
• prompt injection resilience for inbound content
• per-tenant rate limits and abuse detection (TBD)

---

6) Infrastructure

Hosting strategy

MVP recommendation:

• Host the Next.js application on a managed platform optimized for it.
• Deploy the modular monolith backend with the same release cadence as the frontend (single deployable is acceptable for MVP).

Exact providers are TBD.

Environment separation

Required environments:

• local/dev
• staging
• production

Principle: data and secrets must never cross environment boundaries.

CI/CD pipeline

MVP baseline:

• automated checks on pull requests (lint/test/build)
• gated releases to staging → production (TBD)

Secrets management

Requirements:

• secrets never committed to git
• access-controlled secret storage per environment
• rotation support for integration credentials

Storage (documents, assets)

MVP baseline:

• object storage for documents/assets (provider TBD)
• access controlled by org/workspace scope

---

7) Security & compliance foundations

RBAC model

• Roles and permission tokens govern access.
• Sensitive actions require explicit permissions and must be audited.

Reference: Roles & Permissions Model

Workspace isolation

• Isolation is enforced across frontend, backend, data, and AI layers.
• Aggregation across workspaces is permitted only when explicitly documented and permissioned.

Reference: Security & Compliance

Audit events

• Audit is mandatory for high-impact actions (IAM, channels, KB publish, automation, billing).

Data access boundaries

• Minimize PII in logs and analytics.
• Mask secrets everywhere.
• Ensure access checks are enforced server-side (invariant).

---