As software engineers, our job is rapidly shifting from writing boilerplate to designing systems, managing state, and enforcing boundaries around non-deterministic components.
I built Apex (Automated Personal Executive) as a personal testbed to explore these exact challenges. It is a multi-channel orchestration engine that handles context switching across email, calendar management, research, and project scaffolding.
Here is how the system is designed, the constraints I put in place to make it reliable, and what building it taught me about practical AI engineering.
System Design & Infrastructure
The core goal was to build a unified system that operates across existing interfaces with persistent memory, rather than relying on isolated chat sessions.
The architecture consists of three main operational tiers:
- Input Layer: Inbound triggers originate across iMessage (via local CLI bridges), Discord bots, and Gmail hooks. Dedicated tool bindings ensure responses adapt strictly to channel constraints—such as concise plain text for iMessage versus rich formatting for Discord.
- Core Runtime & Router: The main orchestration engine handles authentication, parses slash commands, and manages session state before routing tasks to appropriate execution targets.
- Execution & Persistence Layer: Tasks are delegated either directly to tools or offloaded to specialized sub-agents. State is persisted in local Git repositories, structured CSV logs, a Gmail draft queue, and a local Obsidian Markdown vault.
Key Architecture Choices
- Decoupled Input Adapters: By isolating channel logic from the primary runtime, the core engine processes incoming requests uniformly regardless of whether they originate from an SMS, a Discord message, or an email thread.
- Isolated Sub-Agents: Rather than passing massive system prompts into a single model instance, complex tasks spawn dedicated worker agents with strict Input/Output contracts. This keeps token usage lean and minimizes context degradation.
- File-Based State Management: Instead of introducing heavy database infrastructure for personal scale, persistent state lives in a local Obsidian Markdown vault and structured CSV logs. This makes the system transparent, easily inspectable, and simple to debug.
Security & Guardrails
Integrating AI into personal workflows carries operational risk. The real engineering work lies in designing clear trust boundaries:
- Prompt Injection Protection: Inbound messages are filtered through transport-level allowlists. Requests must match pre-approved phone numbers or Discord user IDs before entering the execution context.
- Human-in-the-Loop Intercepts: The Gmail integration only exposes a draft creation tool. The model physically lacks access to an outbound "send" API endpoint, preventing unintended state mutation.
- Output Verification Constraints: To mitigate hallucinated resources, model outputs referencing web URLs are strictly cross-referenced against active payload returns from the web search tool.
- Two-Phase Execution Prompts: Destructive operations—such as calendar deletions or file overrides—require an explicit, secondary manual confirmation payload before execution.
Core Execution Workflows
1. Context Aggregation (/briefing)
The main engine queries the Google Calendar API, fetches unread emails needing response metadata via the Gmail API, and reads active markdown tasks from Obsidian. It synthesizes this data into a concise, prioritized action list delivered straight to mobile.
2. Isolated Project Scaffolding (/build)
When given a feature description, a specialized Builder sub-agent scaffolds a fresh local directory, injects base constraints via a reusable UI layout module, writes standard frontend code, and executes an initial Git commit without cluttering the main agent's working context.
3. Structured Data Processing (/prospect-trade & /outreach)
For business development workflows in my web agency (Set the Pace Designs), the system executes a two-step pipeline:
- Prospecting: A dedicated agent searches local business registries, flags missing or outdated web presences, and appends clean structured records to a master prospects CSV file.
- Outreach: An outreach agent cross-references historical Gmail threads to prevent duplicate contacts, formats a personalized pitch conforming to UK B2B privacy compliance standards, and saves it directly as a Gmail draft for manual review.
Key Takeaways for Production AI
Building and relying on this system daily highlighted several truths about working with LLMs in real environments:
- Architecture Over Prompt Engineering: Reliable systems come from clean routing, strict schemas, and isolated execution scopes, not endless prompt tweaking.
- Deterministic Guardrails are Mandatory: Non-deterministic models should never have unmediated access to destructive or outbound APIs. Restricting capabilities increases real-world utility by making the system safe to run.
- Output Real Files, Not Just Chat Replies: A chat window is temporary. Real value comes from having the AI generate permanent, structured files you can actually use later—like Git repositories, Markdown notes, or CSV databases.
Technical Summary
- System Name: APEX (Automated Personal Executive)
- Core Stack: Node.js / TypeScript, Claude API, Shell
- Integrations: Gmail API, Google Calendar API, Obsidian, Git, iMessage/Discord Adapters
Command & Routing Map
- /briefing → Handled by Engine Core → Consumes Calendar, Gmail, and Obsidian tasks to output a formatted daily digest.
- /research → Delegated to Research Agent → Performs web searches, synthesizes findings, and outputs structured Markdown files.
- /build → Delegated to Builder Agent → Takes a feature brief, scaffolds local code, and initialises a Git repository.
- /presentation → Delegated to Presentation Agent → Reads designated Obsidian research files and compiles a Reveal.js slide deck.
- /prospect-trade → Delegated to Prospector Agent → Searches trade registries, qualifies web presence, and updates the local prospect dataset.
- /outreach → Delegated to Outreach Agent → Reads prospect CSV records, checks Gmail history, and generates pending Gmail drafts.