​

aiConnected Platform — Foundation PRD

​

1. Purpose & Scope

• Multi-tenant permission architecture
• UI system (shadcn/ui + TweakCN)
• Layout Manager + AI Module Creator
• Memory system (Neurigraph basics)
• Module import system
• Module isolation / standalone access

• Voice AI
• Chat Interface
• Knowledge Base Generator
• Contact Forms / Chat Monitor
• Co-Browser

​

2. Architectural Philosophy — The Lego Brick Model

• Each foundation component lives in its own package with its own folder
• Components communicate through defined contracts (endpoints, events, manifests) — not direct imports
• Replacing or upgrading any component (e.g., swapping the UI library, changing the auth provider, updating the memory system) should not require changes to any other component
• Every module gets its own container, its own repo, and its own direct-access URL from day one
• The complexity is front-loaded into the foundation so that future creation is as frictionless as possible

​

3. Foundation Components

​

3.1 Multi-Tenant Permission Architecture

​

Overview

Super Admin
  └── Agency
        ├── Business
        │     └── End User (via module, not platform login)
        └── Developer (sandboxed, separate trust pipeline)
Personal (isolated, no sub-users)

​

The 13 Permission Types

​

Inheritance Rules

• A Super Admin can impersonate any layer for support and testing
• An Agency Admin can configure what Business Admins are allowed to do
• A Business Admin can configure what their users can do, within the bounds the Agency set
• No layer can grant permissions that exceed their own
• Personal accounts are entirely isolated — no cross-tenant visibility

​

Key Requirements

• Permission checks must be enforced at the API layer, not just the UI
• Role assignments must be auditable (who granted what, when)
• Impersonation sessions must be logged and time-limited
• The permission model must be swappable — if the role structure changes, only the permissions package updates

​

v1 Reference

​

3.2 UI System — shadcn/ui + TweakCN

​

Overview

​

Theming Hierarchy

Platform defaults (Super)
  └── Agency theme (overrides platform defaults)
        └── Business theme (overrides agency defaults, if permitted)

​

AI-Promptable Theming

​

Key Requirements

• All components must come from @aiconnected/ui (the platform’s shadcn wrapper package) — never imported directly from shadcn or any other library
• Hardcoded color values are not permitted anywhere in the codebase
• All colors reference CSS variables only
• Theme inheritance must be explicit and auditable
• Theme changes must be previewable before publishing
• The UI package must be versioned independently of everything else

​

Module UI Flexibility

​

3.3 Layout Manager + AI Module Creator

​

Overview

1. Edit existing screens — drag, drop, resize, and reconfigure layouts using shadcn components as building blocks
2. Create new modules — a conversational AI workflow that builds entire new modules from a description

​

Who Has Access

​

Tab 1: Modules (Edit Existing)

• Layout changes do not go live immediately. They are staged for AI processing.
• When an admin saves a layout, the system’s orchestration AI interprets the layout change, updates the underlying code, and triggers a redeployment via Dokploy.
• The admin receives a notification when the change is live and can preview it before publishing.
• Layout changes are versioned. Any change can be rolled back.
• A pencil icon appears on every screen when an authorized user is logged in. Clicking it opens the Layout Manager directly to that screen.
• The Layout Manager is also accessible from the admin sidebar under “Layout Manager → Modules.”

​

Tab 2: Create New (AI Module Creator)

1. Admin describes what they want in plain language. Example: “Create a team communications module that works like Slack.”
2. The AI researches the functionality — searches for open-source resources, reviews existing endpoints in the SDK, identifies what already exists vs. what needs to be built.
3. The AI presents a plan: here are the endpoints I’ll connect to, here are the ones I need to create, here is the user flow, here is what the UI will look like. The admin reviews and approves or requests changes before anything is built.
4. The AI writes the underlying code using existing platform bricks wherever possible. Novel functionality is minimized and logged as new SDK endpoints.
5. The AI builds the UI using the shadcn component library. If a new component is needed, it is built to be shadcn-compatible.
6. The AI creates the screens, wires the interactions, and generates the module manifest.
7. The admin is notified: “Your module is ready for testing.”
8. The admin tests interactively — making direct edits via the Modules tab, or communicating changes in natural language through the Create New tab.
9. When satisfied, the admin publishes the module, sets access permissions, and it becomes available to enabled users.

• When a new module is published, Agency Admins receive a release notification: what it does, how to enable it, what it costs.
• Agency Admins try it, decide whether to make it available to their business accounts.
• Business Admins receive their own notification if the Agency has enabled it.
• Developers releasing modules through the developer trust pipeline follow a separate review workflow (community sandbox → aiConnected certification).

​

3.4 Memory System — Neurigraph Basics

​

Overview

​

What “Basics” Means for the Foundation

• Session memory — the platform remembers what happened in the current session, including user actions, AI interactions, and module events
• User memory — persistent preferences, history, and context for each user across sessions
• Tenant memory — shared context that applies across all users within an agency or business account (e.g., brand voice, common workflows, frequently asked questions)
• Module memory — each module can read from and write to the shared memory layer, so a call logged by Voice AI is visible to the Chat module and the Knowledge Base

​

Key Requirements

• Memory is stored in Supabase with row-level security enforcing tenant isolation
• The memory API is a shared service — all modules connect to the same memory layer, not separate databases
• Memory is structured (typed, queryable) not just a blob of text
• The memory layer exposes a clean read/write API that modules can call without knowing the storage implementation
• The memory package must be versioned and swappable independently of the modules that use it

​

What Is Deferred

​

3.5 Module Import System

​

Overview

​

Import Process

1. Submission — Developer submits a GitHub repo URL or ZIP archive through the Developer Portal.
2. Manifest check — The system looks for a platform-app.json manifest. If one exists and is valid, the import skips to step 5. If not, the AI-assisted mapping begins.
3. Frontend mapping — The system scans the repo’s UI components and maps them to their shadcn equivalents. A normalization report is generated showing what mapped cleanly, what mapped with modifications, and what could not be mapped (warnings, not blockers).
4. Backend mapping — The system scans API calls, service integrations, and data schemas. Existing SDK endpoints are matched. New functionality that has no SDK equivalent is flagged as requiring new endpoint creation.
5. Plan presentation — The system presents the mapping results to the developer: here is what your app does, here is how it connects to the platform, here is what needs to be built. The developer reviews and approves.
6. Normalization — The system rewrites imports from shadcn to @aiconnected/ui. It replaces hardcoded hex values with CSS variables. The original code is preserved. A normalized artifact is created alongside it.
7. Manifest generation — A platform-app.json is generated or validated, declaring the module’s inputs, outputs, events, permissions, and capabilities.
8. Staging — The module enters the staging registry. It is visible to the developer community for testing and integration. The source code is not exposed — only the capability contract (inputs, outputs, events).
9. Community review — Developers in the community can install the staged module into their sandbox environments and test it against their own modules. Weighted votes determine readiness.
10. aiConnected certification — Modules that pass community review are submitted to aiConnected for security review and stress testing before being published to the live registry.

​

The Living SDK

​

Key Requirements

• The original submitted code is always preserved. Normalization creates a separate artifact.
• Import succeeds even with unmapped components or unrecognized colors — these are warnings, not failures
• Every module in the registry is containerized and isolated (Dokploy)
• Every module gets a unique direct-access URL from the moment it enters the registry (see 3.6)
• The manifest format is defined in packages/app-sdk (extended from v1 with events_emitted and events_consumed fields)

​

3.6 Module Isolation — Standalone Access

​

Overview

​

Why This Is a Day-One Requirement

• Demos — show a single module without exposing the full platform
• Campaigns — link directly to a module as a standalone product experience
• Licensing — grant a third-party company access to a module’s output without giving them platform access
• A/B testing — test variations of a module independently
• Open source — publish a module under an MIT license as a public tool
• Embedding — drop a module into another company’s product

​

How It Works

1. Standalone URL — a direct endpoint (e.g., modules.sec-admn.com/kb-studio or a custom domain) that gives access to the module with configurable authentication (public, token-gated, invite-only, or full auth)
2. Standalone repository — the module’s own Git repo, independent of the platform monorepo

​

Authentication Options for Standalone Access

​

Key Requirements

• Standalone URL and repo are created automatically at module registration — not a manual step
• The module’s container runs independently — it does not depend on other modules being online
• Billing for standalone access is tracked separately and routes through the same Stripe infrastructure
• Standalone access does not bypass the permission model — access mode is set by the admin, not the end user

​

4. What This Foundation Enables

• An Agency Admin logs in, customizes their brand in 10 minutes using the AI-prompted theme editor, and shares a branded link with their client
• A developer builds a new module externally, submits it, and the import system maps it to the platform in one session
• Bob describes a new module in plain language inside the Create New tab, and the AI builds and deploys it
• A module is shared as a public demo via its standalone URL — no login required
• A partner company integrates a single module’s output into their own product via its standalone endpoint
• When the memory system is updated or the UI library is replaced, no modules need to be touched

​

5. Individual PRDs Required

1. Multi-Tenant Permission Architecture — role model, inheritance rules, impersonation, audit logging
2. UI System — shadcn/ui wrapper package, TweakCN integration, theme inheritance, AI-promptable theme editor
3. Layout Manager — Craft.js integration, canvas editor, AI-processed layout saves, redeploy pipeline
4. AI Module Creator — conversational workflow, research layer, plan review, code generation, testing workflow, publish flow
5. Memory System — Neurigraph basics layer, data schema, read/write API, tenant isolation
6. Module Import System — manifest spec, frontend normalization, backend mapping, staging registry, community review, certification
7. Module Isolation — standalone URL generation, standalone repo creation, authentication modes, billing tracking

​

6. Build Sequence

​

7. v1 Reference Notes

• packages/permissions/src/auth.js — 13 role constants, group helpers
• packages/app-sdk/src/manifests.js — manifest spec baseline
• packages/branding/src/index.js — mergeTheme() logic and token names

​

8. Definition of Done

• All 13 permission types are enforced at the API layer (not just UI) and tested
• A theme can be changed for a tenant without touching another tenant’s theme
• A layout change in the canvas editor deploys to production without manual developer intervention
• A new module can be described in plain language and the AI builds and deploys it end-to-end
• An externally-built module can be imported, normalized, and staged without manual code editing
• Every registered module has a working standalone URL accessible without a platform login
• Any foundation component (UI system, permission system, memory layer) can be replaced without changes to modules that depend on it