Skip to main content

Architecture Overview

This document provides a comprehensive overview of the Hello Battle Card platform architecture for developers and contributors.

System Architecture​

Hello Battle Card is built on a modern serverless architecture:

  • Frontend: SvelteKit webapp (TypeScript, Svelte 5)
  • Backend: Azure Functions (TypeScript, Durable Functions)
  • Database: Azure Cosmos DB (NoSQL, Graph-on-NoSQL pattern)
  • Authentication: Firebase Auth
  • AI: Azure OpenAI, Google Gemini
  • Storage: Azure Blob Storage
  • Messaging: Azure Service Bus

High-Level Flow​

User Request → SvelteKit API Route → Azure Functions Orchestrator → Activities → Cosmos DB
                                                                    ↓
                                                              Service Bus (async)

Webapp Architecture​

Tech Stack​

  • Framework: SvelteKit 2.x with Svelte 5 (runes-based reactivity)
  • Language: TypeScript 5.4+
  • Styling: Tailwind CSS 4.x
  • State Management: Svelte stores + Svelte 5 runes
  • Build Targets: Azure Container Apps or Azure Static Web Apps

Project Structure​

apps/webapp/src/
├── lib/
│   ├── components/          # Reusable Svelte components
│   ├── server/              # Server-only code
│   │   ├── cosmos/          # Cosmos DB access layer
│   │   └── ai/              # AI provider and tools
│   ├── stores/              # State management
│   ├── types/               # TypeScript types
│   └── utils/               # Utilities
└── routes/
    ├── (app)/               # Authenticated routes
    └── api/                 # API route handlers

Key Features​

  • Multi-tenant Architecture: Workspaces based on email domain
  • Role-Based Access Control: OWNER, ADMIN, EDITOR, VIEWER
  • Whitelabel Support: Custom domains and branding (Enterprise)
  • AI Chat Integration: Autonomous agent with tool-use
  • Knowledge Graph: Graph-on-NoSQL visualization

Functions Architecture​

Tech Stack​

  • Runtime: Azure Functions v4 (Node.js 20.x)
  • Orchestration: Azure Durable Functions
  • Language: TypeScript 5.4+
  • Database: Azure Cosmos DB
  • Messaging: Azure Service Bus

Project Structure​

apps/functions/src/
├── activities/              # Durable Functions activities
│   ├── competitor/          # Competitor-specific activities
│   └── ...
├── orchestrators/          # Durable Functions orchestrators
│   ├── company-research.ts  # Unified company research
│   ├── offering-research.ts # Offering discovery/analysis
│   └── ...
├── triggers/                # HTTP and change feed triggers
├── core/                    # Core business logic services
└── shared/                  # Shared utilities
    ├── cosmos/              # Cosmos DB access layer
    └── ...

Orchestration Patterns​

  • Fan-Out/Fan-In: Parallel execution with result aggregation
  • Claim Check: Store large data in blob storage, pass reference
  • Sub-Orchestrators: Break complex workflows into sub-orchestrators
  • Retry Policies: Automatic retries for transient failures

Data Model​

Core Entities​

  • Tenant: Workspace/organization
  • User: Authenticated users
  • Competitor: Competitor companies
  • Offering: Products/services (ours and competitors')
  • Battlecard: Generated battlecards
  • MatrixCell: Competitive matrix cells
  • IntelItem: Research findings and evidence
  • Job: Background job tracking
  • KnowledgeTree: RAPTOR knowledge trees

Knowledge Graph​

Graph-on-NoSQL pattern in Cosmos DB:

Node Types: ORGANIZATION, OFFERING, CAPABILITY, COMPETITOR, PERSON, MARKET_EVENT, TOPIC, DOCUMENT, DEAL, ARGUMENT

Edge Types: IMPLEMENTS, COMPETES_WITH, HAS_OFFERING, RELATED_TO, etc.

Authentication & Authorization​

Authentication Flow​

  1. Client: Firebase Auth handles login
  2. Server Hook: Validates Firebase token, loads user/tenant
  3. Route Protection: requireAuth() helper checks authentication
  4. API Routes: Use requireAuth(event) to get tenant/user

Authorization​

  • Role-Based Access Control: OWNER, ADMIN, EDITOR, VIEWER
  • Plan-Based Limits: STANDARD, PRO, ENTERPRISE
  • API Key Authentication: Enterprise plan feature

API Design​

REST API Conventions​

  • Resource-based URLs: /api/competitors, /api/competitors/[id]
  • HTTP Methods: GET, POST, PUT, DELETE
  • JSON responses with consistent error format

MCP Server​

Model Context Protocol server for AI agent integration:

  • Endpoint: /mcp
  • Protocol: JSON-RPC 2.0
  • Tools: get_competitor, list_competitors, get_battlecard, etc.

Performance Optimizations​

Cosmos DB Query Optimization​

  • Selective Projection: Only fetch required fields (60-95% memory reduction)
  • Indexed Queries: All queries use indexed fields
  • Pagination: Large result sets paginated

Memory Optimization​

  • Streaming: Large data streams instead of loading into memory
  • Lazy Loading: Load data only when needed
  • Garbage Collection: Explicit cleanup of large objects

Security​

  • Authentication: Firebase Auth with ID token validation
  • Authorization: Role-based access control (RBAC)
  • API Keys: Scoped API keys for Enterprise plans
  • Input Validation: Zod schemas for API inputs
  • XSS Protection: Svelte's built-in escaping
  • CSRF Protection: SvelteKit's built-in CSRF protection

Development​

Local Development​

Webapp:

cd apps/webapp
npm install
npm run dev

Functions:

cd apps/functions
npm install
cp local.settings.json.example local.settings.json
npm run dev

Testing​

  • Unit tests: npm test (functions)
  • Manual testing: Test scripts for Service Bus messages
  • E2E testing: Planned for future

Deployment​

Webapp​

  • Azure Container Apps: Containerized deployment
  • Azure Static Web Apps: Static site hosting

Functions​

  • Azure Functions: Consumption or Premium plan
  • Auto-scaling: Automatic scaling based on load