LEX AI Architecture Snapshot

The components of the installed LEX AI package: the unified server, ten mode surfaces, the payload model across seven environments, resilience, and persistence.

A
Written By Atakan KayaLast updated 3 months ago

LEX AI Architecture Snapshot

This summary is based on the repository architecture reference. It describes what the installed package is made of, for readers who need to reason about its behaviour rather than operate it.

Core components

  • A unified FastMCP server entry point, lex-mcp, which resolves the mode at boot and exposes a single tool surface.
  • Ten mode surfaces: brief, forward, backward, edit, review, test, input, deploy, MVP generator, and MVP completion.
  • A remote MCP transport bridge, over stdio or HTTP, to the authoritative Lex backend. Most forward-style step bodies and every Deploy step body come from it; the technical-map wiki and sync steps are served locally.
  • Shared services registered on every surface: the question channel (ask_user_question, record_user_answer) and the file readers (read_input_file, render_pdf_pages).
  • An analytics pipeline for workflow events and diagnostics.

Package payload model

Agent definitions, instructions, and slash-command assets are packaged from mode-specific .github directories inside each source package. That canonical tree is delivered verbatim to the GitHub Copilot surfaces and translated into the native layout of every other supported environment — seven environments served by five payload dialects. Environments without native subagents receive the same agents under a neutral .lex/agents/ tree plus an explicit delegation protocol in their workspace rules, so the guardrails do not vary by editor; only the spawning mechanism does.

Runtime resilience

  • Tool-surface epoch tracking across mode switches.
  • Stale-tool middleware turns a call to a tool that is no longer mounted into a structured troubleshooting payload naming the active and suggested mode, rather than a raw method-not-found error.
  • A mode switch swaps the mounted provider in place and refreshes the client's tool list. If the live swap fails, the server persists a one-shot override and exits so the IDE restarts it in the intended mode.

Persistence

Workflow state is persisted in a per-mode session manifest — .lex-workflow/, .lex-reverse/, .lex-test/, and the equivalent for each other mode — alongside step summaries. This is what makes resume possible, and what lets the server detect user edits between steps and rewind to the earliest affected step.

Configuration surface

Every MCP configuration LEX AI writes uses the single server entry name lex-mcp-local, because a stale namespace grants the assistant no tool access at all. Writes are merge-preserving and atomic: unrelated servers, unknown keys, and TOML comments survive. CLAUDE.md and AGENTS.md are never overwritten — only the region between the managed-block markers is rewritten.

See Tool surfaces, Mode switching, and Files and questions.

Was this helpful?

Your feedback shapes what we write next.