Skip to content

CodeDesign.md

Latest commit

 

History

History
119 lines (82 loc) · 3.82 KB

CodeDesign.md

File metadata and controls

119 lines (82 loc) · 3.82 KB

System Design (App + Platform)

This project is split into two independent products:

  1. App/: business logic and user-facing app UI.
  2. Platform/: generic deployment control plane.

The Platform must remain app-agnostic. The App must remain platform-portable.

App Design

App responsibilities

  • Define domain behavior only (agents, tools, orchestrator, models, services).
  • Expose APIs required for orchestration.
  • Serve the App web UI (dummy email input + response + trace).
  • Provide config.yaml describing components and service base names (no host ports).

App artifact groups

  • Agents/ or inboxpilot/agents/: classify, fetch, respond.
  • Tools/ or inboxpilot/tools/: calendar, imap, draft (and future tools).
  • Services/ or services/: HTTP runtime entrypoints per component.
  • Models/: wrappers for LLM/cloud providers.

Concrete implementations inherit from base abstractions for consistent behavior.

App runtime contracts

  • Orchestrator is the main entrypoint for end-user workflow.
  • Agent-to-agent and orchestrator-to-agent calls use A2A-style HTTP communication.
  • Event/trace flow can use Kafka.
  • App code must run on python:3.11-slim.
  • No platform-specific hardcoding in app logic.

App packaging boundary

  • The App is uploaded as zip source.
  • Docker build/deploy assets are produced by Platform during runtime.

Platform Design

Platform is a generic UI + backend to build, store, deploy, and operate uploaded apps.

Platform UI flow

  1. Upload App zip.
  2. Inspect config.yaml and discover orchestrator/agents/tools.
  3. Ask operator for host ports per discovered component.
  4. Build images from uploaded source.
  5. Store build artifacts in MongoDB repository.
  6. Deploy selected build from repository.
  7. Show status, logs, endpoint URLs, and live instance state.

Four Platform parts (modular)

Part I: Repository

Focus: persistent artifact store for portability and multi-machine readiness.

  • Store build metadata, compose payloads, and image archives.
  • Use MongoDB + GridFS.
  • Support lookup by build_id (or latest by deployment_id).
  • Deploy stage must consume repository artifacts, not source rebuild.

Part II: Infra and Runtime

Focus: runtime materialization and execution environment.

  • Generate runtime Dockerfile and compose specs from app config + selected ports.
  • Keep host-port mappings platform-driven.
  • Support Kafka sidecar where required for event routing.
  • Keep runtime state files for active deployment and in-progress operation.

Part III: Build and Package

Focus: deterministic image build and artifact publication.

  • Build images with Docker Compose build profile.
  • Export built images (docker save) and push archives to GridFS.
  • Persist deploy compose payload and component/port metadata.
  • Emit explicit build checkpoints and logs.

Part IV: Orchestration and Communications

Focus: operation lifecycle and system observability.

  • Orchestrate inspect -> build -> deploy pipeline.
  • Manage stop previous / start new deployment lifecycle.
  • Provide API endpoints for status and recent logs.
  • Surface command-level progress to UI for debugging clarity.

Non-Functional Rules

  • Keep modules small and explicit.
  • Prefer real failures over silent fallbacks.
  • Keep code concise; use comments only for non-obvious logic.
  • No test script requirement in this baseline.
  • Single-machine operation is the default mode.
  • run.sh starts Platform and ensures MongoDB is available.

Minimum Contracts

App must provide

  • config.yaml with app, agents, and tools sections.
  • Python source compatible with python:3.11-slim.
  • Orchestrator API and App UI endpoint.

Platform must provide

  • Upload + inspect APIs.
  • Build API (source -> images -> repo artifact).
  • Deploy API (repo artifact -> running containers).
  • Status/log APIs for UI observability.