Architecture Overview

HotCRM is built on a modern, scalable architecture that emphasizes type safety, modularity, and developer experience. This document provides a high-level overview of the system architecture.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Co-Pilot    │  │   ObjectUI   │  │  Components  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                            ▲
                            │ REST / GraphQL
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Intelligence Layer                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Generative  │  │   Predictive │  │    Audit     │          │
│  │    Agents    │  │    Models    │  │  Trust Wall  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                            ▲
                            │ Context & Actions
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Application Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Express    │  │   Actions    │  │   Triggers   │          │
│  │    Server    │  │   (API)      │  │   (Logic)    │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                            ▲
                            │ ObjectQL (Type-Safe)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Data Layer                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   ObjectQL   │  │   Metadata   │  │   Vector     │          │
│  │   Engine     │  │   Registry   │  │    Store     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. Frontend Layer

The frontend is more than just forms. It includes the Co-Pilot interface that overlays every application, allowing users to converse with their data.

Technologies:

ObjectUI Engine: Dynamic UI rendering based on metadata. (Part of Runtime)
React Server Components: For high-performance rendering.

2. Intelligence Layer

The distinct layer that processes intent, prediction, and generation.

Components:

Generative Agents: Autonomous workers that perform tasks.
Prophet Engine: Predictive models for scoring and forecasting.

3. Application Layer

The middle tier handles business logic validation and orchestration.

Components:

ObjectStack Runtime: The standard engine powering the system.
Triggers: Transactional logic defined in packages/*.
Actions: Callable functions exposed to the API.

4. Data Layer

The foundation. It manages structured (relational) and unstructured (vector) data side-by-side.

Components:

ObjectQL Engine: Translates high-level queries into optimized database calls. (Part of Runtime)
Metadata Registry: Loads objects from packages/*.
Vector Store: Stores embeddings for semantic search (RAG).

Design Principles

1. Metadata-Driven

Everything in HotCRM is defined through metadata:

// Object definition in TypeScript
export default const Account: ObjectSchema = {
  name: 'Account',
  label: 'Account',
  fields: [...],
  relationships: [...],
  triggers: [...],
  listViews: [...]
};

Benefits:

Single source of truth
Type safety
Easy customization
Version control

2. Type-Safe

Full TypeScript implementation with strict type checking:

// Type-safe queries
const accounts: Account[] = await db.find('Account', {
  filters: [['Industry', '=', 'Technology']]
});

// Compile-time validation
accounts.forEach(account => {
  console.log(account.Name); // ✅ Type-safe
  console.log(account.InvalidField); // ❌ Compile error
});

3. Modular & Extensible

Clean package separation allows easy customization and extension.

4. AI-First

AI capabilities are core to the platform, not add-ons.

5. Developer-Friendly

Focus on developer experience with excellent tooling and documentation.

Data Flow

Read Operation

User Request
    ↓
Express Server (REST API)
    ↓
ObjectQL Query Engine
    ↓
Metadata Registry (validate schema)
    ↓
Database Access
    ↓
Return Data (JSON)

Write Operation

User Request (Create/Update)
    ↓
Express Server (validation)
    ↓
Before Triggers (business logic)
    ↓
ObjectQL Mutation Engine
    ↓
Database Write
    ↓
After Triggers (automation)
    ↓
Return Result

Monorepo Structure

HotCRM uses a multi-package monorepo architecture with 9 business packages:

hotcrm/
├── packages/
│   ├── core/                 # Foundation & ObjectQL Engine
│   ├── crm/                  # Sales Cloud (13 objects)
│   ├── marketing/            # Marketing Cloud (2 objects)
│   ├── products/             # Product Catalog (9 objects)
│   ├── finance/              # Finance & Billing (4 objects)
│   ├── support/              # Service Cloud (21 objects)
│   ├── hr/                   # HR Cloud (16 objects)
│   ├── ai/                   # AI Services & ML Models
│   ├── ui/                   # UI Components
│   └── server/               # Application Server
├── pnpm-workspace.yaml       # Workspace config
└── package.json              # Root scripts

Total: 65 objects across 6 business clouds

Package Dependencies:

@hotcrm/server (Application Assembly)
  ├── @hotcrm/core
  ├── @hotcrm/crm (13 objects)
  ├── @hotcrm/marketing (2 objects)
  ├── @hotcrm/products (9 objects)
  ├── @hotcrm/finance (4 objects)
  ├── @hotcrm/support (21 objects)
  ├── @hotcrm/hr (16 objects)
  ├── @hotcrm/ai (ML models)
  └── @hotcrm/ui

Domain Packages (crm, marketing, products, finance, support, hr)
  └── @hotcrm/core

@hotcrm/ai
  └── @hotcrm/core

@hotcrm/ui
  └── @hotcrm/core

@hotcrm/core (no dependencies)

Vertical Slice Architecture

Each domain package is a self-contained vertical slice:

@hotcrm/crm/
├── src/
│   ├── account.object.ts      # Schema
│   ├── contact.object.ts      # Schema
│   ├── opportunity.object.ts  # Schema
│   ├── opportunity.hook.ts    # Business Logic
│   ├── ai_briefing.action.ts  # Custom Action
│   └── index.ts               # Exports
└── package.json

Benefits:

Complete feature isolation
Easy to understand and maintain
Can be deployed independently
Clear ownership

Security Architecture

Authentication & Authorization

// Future: JWT-based authentication
const user = await authenticate(req.headers.authorization);

// Row-level security
const accounts = await db.find('Account', {
  filters: [['OwnerId', '=', user.Id]]
});

Field-Level Security

// Field permissions based on user role
if (user.role !== 'Admin') {
  delete account.AnnualRevenue; // Hide sensitive data
}

Audit Trail

All data operations are logged for compliance:

{
  timestamp: '2026-01-27T10:00:00Z',
  user: 'john.doe@acme.com',
  action: 'UPDATE',
  object: 'Account',
  recordId: 'acc_123',
  changes: {
    Status: { old: 'Prospect', new: 'Customer' }
  }
}

Scalability

Horizontal Scaling

The stateless application layer can be scaled horizontally:

Load Balancer
    ├── Server Instance 1
    ├── Server Instance 2
    └── Server Instance 3
          ↓
    Database Cluster

Caching Strategy

Metadata Caching: Object schemas are cached in memory
Query Results: Frequently accessed data is cached
API Responses: Cache at CDN level

Performance Optimization

Lazy loading of related records
Batch operations for bulk data
Database query optimization
Efficient indexing

Technology Stack

Backend

Runtime: Node.js 18+
Language: TypeScript 5+
Framework: Express.js
Package Manager: pnpm 8+

Frontend (Future)

Framework: React / Next.js
Styling: Tailwind CSS
State Management: React Query / Zustand

Database (Future)

Primary: PostgreSQL (relational data)
Cache: Redis (session, cache)
Search: Elasticsearch (full-text search)
Vector DB: Pinecone (AI embeddings)

AI/ML

LLM: OpenAI GPT-4 / GPT-3.5
Embeddings: OpenAI text-embedding-ada-002
NLP: Custom models for entity extraction

Next Steps

Explore specific architectural components:

Architecture Overview

On this page