Skip to Content

SAM AI Architecture Brainstorming Session

SAM AI Architecture Brainstorming Session

Date: 2025-12-06
Participants: Anthony (User), Claude (CTO Architect)
Repo: D:\SAMAI-18-SaaS\github-repos\05-samai-core
Status: 🟡 Draft - Brainstorming in Progress

📋 Table of Contents

  1. Current State Analysis
  2. The Problem Statement
  3. Current Architecture Map
  4. Open Questions
  5. Brainstorming: Possible Solutions
  6. Next Steps

🎯 Current State Analysis

What We Know (Verified 2025-12-06)

Repository Structure

D:\SAMAI-18-SaaS\github-repos\
├── 04-samai-brain/          # OLD: ai_brain module (in "debug hold")
└── 05-samai-core/           # CURRENT: Active development
    ├── ai_sam_base/         # DATA LAYER: Models that were split from ai_brain
    ├── ai_sam/              # SKIN LAYER: Views, static assets, no models
    ├── ai_sam_workflows_base/  # DATA LAYER: Workflow-specific models
    ├── ai_sam_workflows/    # SKIN LAYER: Workflow UI, controllers, static
    └── ai_sam_cache_manager/   # Utility module

Module Breakdown: What Lives Where

ai_sam_base (Data Layer - 44 Models)

Purpose: Core SAM AI data models (split from original ai_brain)

Key Models:
- ai_conversation.py - Conversation management
- ai_message.py - Message storage
- ai_agent_definition.py - Agent configurations
- ai_agent_knowledge.py - Agent knowledge base
- ai_workspace.py - Workspace management
- ai_context_builder.py - Context assembly
- ai_memory_*.py - Memory system (config, search logs, import)
- ai_provider_*.py - AI provider/model management
- ai_service*.py - Service definitions
- api_credentials.py - API credential storage
- canvas_platform.py - Canvas platform definitions
- sam_*.py - SAM behavior, environment, user profiles, settings
- mcp_*.py - MCP server configs

Contains:
- ✅ Python models (.py files)
- ✅ Security rules (security/)
- ✅ Data files (data/)
- ❌ NO views
- ❌ NO static assets
- ❌ NO controllers

ai_sam (Skin Layer - Presentation)

Purpose: UI/UX for core SAM AI features

Structure:

ai_sam/
├── __manifest__.py
├── views/              # XML views for ai_sam_base models
├── static/
│   └── src/
│       ├── vendor_library/    # 🚨 N8N icons & metadata JSONs live here
│       └── [other JS/CSS]
├── data/               # UI-related data (menus, actions)
└── security/           # View-level security

Contains:
- ✅ XML views (forms, trees, search views)
- ✅ Static assets (JS, CSS, icons, vendor_library)
- ✅ Menu definitions
- ❌ NO Python models
- ❌ NO business logic

Key Asset: static/src/vendor_library/
- N8N node icons (SVG/PNG)
- N8N metadata registry (_registry/node_metadata.json)
- API config files

ai_sam_workflows_base (Data Layer - 15 Models)

Purpose: Workflow automation data models (split from original ai_brain)

Key Models:
- n8n_simple_nodes.py - N8N node definitions (computes icon URLs pointing to ai_sam)
- n8n_simple_extractor.py - N8N node extraction/scanning
- canvas.py - Canvas data model
- nodes.py - Workflow node definitions
- executions.py - Workflow execution tracking
- workflow_templates.py - Template storage
- business_unit.py - Business unit management
- api_credentials.py - Workflow-specific credentials

Contains:
- ✅ Python models
- ✅ Security rules
- ✅ Data files
- ❌ NO views
- ❌ NO static assets
- ❌ NO controllers

ai_sam_workflows (Skin Layer - Presentation)

Purpose: UI/UX for workflow automation

Structure:

ai_sam_workflows/
├── __manifest__.py
├── controllers/        # HTTP endpoints (RPC, canvas API)
├── views/              # XML views for workflow models
├── static/
│   └── src/
│       └── automator/
│           └── n8n/
│               └── overlays/
│                   └── overlay_manager.js  # Frontend that USES icons from ai_sam
└── data/

Contains:
- ✅ Controllers (Python HTTP endpoints)
- ✅ XML views
- ✅ Frontend JavaScript (overlay UI)
- ❌ NO Python models
- ❌ NO icon files (uses ai_sam's vendor_library)

🔴 The Problem Statement

What Anthony Said:

"ai_brain basically became too big, then there was a nightmare to find a bug, so currently ai_brain models are split across the sam ai base and sam ai workflows base modules, there is still models in ai_brain needing to be 'worked on' yet not for now. then we had 'the skins' on top of the base modules this was 'views' .js etc, not data as such, although we have json and icons sitting at the skin level"

Translation to Technical Problems:

Problem 1: ai_brain Explosion

  • Symptom: ai_brain module grew too large
  • Impact: Debugging became a nightmare
  • Solution Attempted: Split models into ai_sam_base and ai_sam_workflows_base
  • Current Status: ai_brain still exists (in 04-samai-brain repo, "debug hold")
  • Question: What models still live in ai_brain? What's the migration plan?

Problem 2: Data vs Presentation Confusion

  • Symptom: "Skins" (ai_sam, ai_sam_workflows) contain data assets (JSON, icons)
  • Expected: Skins = views + JS only
  • Reality: Skins = views + JS + vendor_library (icons/metadata)
  • Impact: Unclear where AI agents should put code/assets

Problem 3: Cross-Module Dependencies

  • Symptom: ai_sam_workflows frontend depends on ai_sam static assets
  • Example: n8n_simple_nodes.py (in workflows_base) computes URLs pointing to ai_sam/static/vendor_library
  • Impact:
  • Frontend constructs wrong paths (icon bug we just fixed)
  • Duplication risk (temptation to copy icons to workflows module)
  • AI agents don't know which module owns what

🗺️ Current Architecture Map

The "Base + Skin" Pattern (As Implemented)

┌─────────────────────────────────────────────────────────────┐
│ LAYER 1: DATA (Base Modules)                                │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ai_sam_base/                  ai_sam_workflows_base/       │
│  ├── 44 models                 ├── 15 models                │
│  ├── Core SAM logic            ├── Workflow logic           │
│  └── NO views/UI               └── NO views/UI              │
│                                                              │
└──────────────────┬──────────────────────────────────────────┘
                   │ (depends on)
┌──────────────────▼──────────────────────────────────────────┐
│ LAYER 2: PRESENTATION (Skin Modules)                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ai_sam/                       ai_sam_workflows/            │
│  ├── Views for ai_sam_base     ├── Views for workflows_base│
│  ├── Static assets             ├── Controllers             │
│  ├── 🚨 vendor_library/        ├── Frontend JS             │
│  │   (icons, JSON metadata)    └── Uses ai_sam assets      │
│  └── NO models                                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

🚨 ANOMALY: vendor_library is DATA, but lives in SKIN layer

The Dependency Web

ai_sam_workflows (skin)
    │
    ├─── depends on ──→ ai_sam_workflows_base (data)
    │                       │
    │                       └─── n8n_simple_nodes.py
    │                             └── computes icon_svg_url
    │                                 pointing to: /ai_sam/static/vendor_library/
    │
    └─── depends on ──→ ai_sam (skin) 🚨 SKIN DEPENDS ON SKIN!
                            │
                            └── static/src/vendor_library/
                                ├── [Supplier]/icon.svg
                                └── _registry/node_metadata.json

Problem: Skins depending on other skins violates layer separation!

❓ Open Questions

Strategic Questions (Need Anthony's Input)

Q1: What is the ai_brain endgame?

  • [ ] Option A: Fully deprecate ai_brain (all models migrated to base modules)
  • [ ] Option B: Keep ai_brain as a separate module (distinct purpose)
  • [ ] Option C: Merge base modules back into ai_brain (reverse the split)

Anthony, which direction?

Q2: Where SHOULD vendor_library live?

Current: ai_sam/static/src/vendor_library/ (skin layer)

Option A: Keep in ai_sam (Shared Assets Module)

ai_sam/
├── static/src/vendor_library/
│   ├── [Supplier]/icons.svg
│   └── _registry/node_metadata.json
└── (no models, no business logic)

Pros:
- ✅ Already there
- ✅ Reusable across multiple modules
- ✅ Single source of truth

Cons:
- ❌ ai_sam is a "skin" but contains data
- ❌ Violates "skins have no data" principle

Option B: Move to ai_sam_workflows_base (Data Module)

ai_sam_workflows_base/
├── models/
│   └── n8n_simple_nodes.py (already here)
└── static/vendor_library/  (MOVE HERE)
    ├── [Supplier]/icons.svg
    └── _registry/node_metadata.json

Pros:
- ✅ Data lives in data layer (clean separation)
- ✅ Close to models that use it

Cons:
- ❌ Can't reuse N8N knowledge in other modules
- ❌ Static assets in a "base" module is unusual in Odoo

Option C: Create ai_sam_n8n_library (Dedicated Module)

ai_sam_n8n_library/
├── static/vendor_library/
│   ├── [Supplier]/icons.svg
│   └── _registry/node_metadata.json
└── __manifest__.py (no models, pure asset library)

Pros:
- ✅ Clear ownership (N8N library owns N8N assets)
- ✅ Reusable across modules
- ✅ Follows single-responsibility principle

Cons:
- ❌ More modules to manage
- ❌ Might be overkill for one folder

Anthony, which option feels right?

Q3: Should base modules have ANY static assets?

Current:
- ai_sam_base: NO static assets ✅
- ai_sam_workflows_base: NO static assets ✅

But:
- ai_sam (skin): Has vendor_library (data assets) ❌

Standard Odoo Practice:
- Base modules CAN have static assets (like default images)
- But usually: models in base, views/assets in skin

Question: Is vendor_library an exception (shared asset library), or should it follow strict separation?

Q4: What is the three-layer architecture intent?

You mentioned earlier:

"ai_brain (data) → ai_sam (framework) → branches (features)"

But current reality:

ai_sam_base (data)
    ↓
ai_sam (framework/skin)
    ↓
ai_sam_workflows_base (data) ← 🚨 BREAKS LAYER!
    ↓
ai_sam_workflows (skin)

Question: Should it be:

Option A: Two-Layer (Base + Skin)

Data Layer: ai_sam_base, ai_sam_workflows_base
Skin Layer: ai_sam, ai_sam_workflows

Option B: Three-Layer (Data → Framework → Features)

Layer 1 (Data): ai_sam_base
Layer 2 (Framework): ai_sam
Layer 3 (Features): ai_sam_workflows_base + ai_sam_workflows

Option C: Something else entirely?

💡 Brainstorming: Possible Solutions

Approach 1: Strict Two-Layer Separation

Principle: Data in base, presentation in skin, assets follow purpose

DATA LAYER (Models + Related Assets)
├── ai_sam_base/
│   ├── models/ (44 core models)
│   └── data/
│
└── ai_sam_workflows_base/
    ├── models/ (15 workflow models)
    └── static/vendor_library/  ← MOVE HERE
        ├── [Supplier]/icons.svg
        └── _registry/node_metadata.json

PRESENTATION LAYER (Views + Controllers + UI)
├── ai_sam/
│   ├── views/ (for ai_sam_base)
│   ├── static/src/ (UI JS/CSS)
│   └── NO vendor_library
│
└── ai_sam_workflows/
    ├── controllers/
    ├── views/ (for workflows_base)
    └── static/src/ (overlay_manager.js)

Pros:
- ✅ Clean separation (data vs presentation)
- ✅ Assets live with models that use them

Cons:
- ❌ If you want to reuse N8N library elsewhere, it's locked in workflows_base
- ❌ Breaking change (move assets)

Effort: Medium (file moves + path updates)

Approach 2: Shared Asset Library Pattern

Principle: Create dedicated modules for shared assets

ASSET LIBRARY LAYER
└── ai_sam_library/
    ├── static/vendor_library/
    │   ├── [Supplier]/icons.svg
    │   └── _registry/node_metadata.json
    └── __manifest__.py (no models, pure library)

DATA LAYER
├── ai_sam_base/ (depends on ai_sam_library)
└── ai_sam_workflows_base/ (depends on ai_sam_library)

PRESENTATION LAYER
├── ai_sam/ (depends on ai_sam_base + ai_sam_library)
└── ai_sam_workflows/ (depends on workflows_base + ai_sam_library)

Pros:
- ✅ Reusable across any module
- ✅ Clear ownership (library owns assets)
- ✅ Follows "shared resources" pattern

Cons:
- ❌ More modules (complexity)
- ❌ Every module depends on library

Effort: Medium-High (new module + dependency updates)

Approach 3: Keep Current, Document Rules

Principle: Accept that ai_sam is a "framework module" (not pure skin)

FRAMEWORK LAYER (Shared Services + Assets)
└── ai_sam/
    ├── static/vendor_library/ (shared N8N library)
    ├── views/ (core views)
    └── static/src/ (core JS)

DATA LAYERS
├── ai_sam_base/ (core data)
└── ai_sam_workflows_base/ (workflow data)
    └── models/n8n_simple_nodes.py
        └── computes URLs → /ai_sam/static/vendor_library/

FEATURE LAYER
└── ai_sam_workflows/
    ├── controllers/
    ├── views/
    └── static/ (uses ai_sam assets)

Pros:
- ✅ No file moves (works today)
- ✅ Pragmatic (ai_sam already acts as framework)
- ✅ Low effort (just document the pattern)

Cons:
- ❌ Violates "pure separation" principle
- ❌ AI agents might still be confused

Effort: Low (documentation only)

Approach 4: Merge Base Modules into Skins

Principle: Each feature is self-contained (models + views together)

CORE MODULE
└── ai_sam/
    ├── models/ (MERGE ai_sam_base models here)
    ├── views/
    ├── static/
    └── data/

WORKFLOW MODULE
└── ai_sam_workflows/
    ├── models/ (MERGE workflows_base models here)
    ├── controllers/
    ├── views/
    ├── static/vendor_library/ (MOVE HERE)
    └── data/

Pros:
- ✅ Self-contained (everything for workflows in one place)
- ✅ Easier for AI agents (one module = one feature)
- ✅ Standard Odoo pattern (models + views together)

Cons:
- ❌ Reverses the split you already did
- ❌ Might re-create "too big" problem
- ❌ Can't separate data from presentation

Effort: High (merge modules, extensive testing)

🎯 Next Steps

What We Need to Decide Together:

  1. Answer Q1: What happens to ai_brain? (Deprecate, keep, merge back)
  2. Answer Q2: Where should vendor_library live? (Keep, move, or create library module)
  3. Answer Q3: Is ai_sam a "skin" or a "framework"? (Naming/purpose clarity)
  4. Answer Q4: Two-layer or three-layer architecture? (Data → Presentation, or Data → Framework → Features)

Proposed Discussion Flow:

Step 1: Answer Strategic Questions (This document)

  • Anthony provides answers to Q1-Q4
  • We discuss trade-offs of each approach

Step 2: Choose Approach (Next session)

  • Pick one of the 4 approaches (or hybrid)
  • Identify migration steps (if needed)

Step 3: Create Migration Plan (If changes needed)

  • List files to move
  • Update dependencies
  • Test plan

Step 4: Document Architecture Rules (Always needed)

  • Write AI agent guidance: "Where to put X"
  • Create ownership matrix (module → responsibilities)
  • Define forbidden patterns

📝 Notes for Next Discussion

Things to Explore:

  • [ ] List models still in ai_brain (04-samai-brain repo)
  • [ ] Check if any code references old ai_brain imports
  • [ ] Identify other "data living in skins" cases (besides vendor_library)
  • [ ] Review manifest dependencies (who depends on whom)

Questions for Anthony:

  • What's your gut feeling on the 4 approaches?
  • Is there urgency to fix this, or can we evolve gradually?
  • Are there other modules (beyond these 5) we should consider?
  • Do you have a preference: fewer modules (simple) vs more modules (separated)?

🔚 End of Brainstorming Document

Status: Awaiting Anthony's input on strategic questions

Next Action: Anthony reviews Q1-Q4 and picks preferred approach

Created by: Claude (CTO Architect)
Date: 2025-12-06

Was this helpful?