Harmonizing AI Code Generation with Centralized System Design

In the era of AI-assisted coding, we often encounter a specific friction point: Alignment. You might have an LLM generating a beautiful React frontend, another agent scaffolding your Go backend, and a third writing Terraform scripts. But when you put them together, the frontend calls /users while the backend exposes /v1/user, and the infrastructure hasn't opened the correct ports.

The missing piece isn't better prompts—it's Centralized System Design.

To achieve harmonious code generation across the stack, we need to treat System Design not as a static document, but as a living, consumable Source of Truth.

The Chaos of Fragmented Context

When you ask an AI to "build a todo app," it hallucinates a schema. If you ask it to "build the frontend for that todo app" in a new session, it hallucinates a different schema.

To fix this, we need a repository that dictates reality. This repository shouldn't contain application code. It should contain Intent.

The Power of Domain-Driven Structure

The most efficient way to organize this "Intent" for LLM consumption is through Domain-Driven Structure. Instead of organizing files by type (e.g., a folder for all OpenAPIs, a folder for all Markdown files), we organize them by Domain.

Imagine a directory structure like this:

design/
  ├── identity/
  │   ├── auth-flow.md          # Context & Business Logic
  │   ├── api.yaml              # OpenAPI (REST)
  │   └── events.yaml           # AsyncAPI (Events)
  ├── payments/
  │   ├── payment-gateway.md
  │   └── api.yaml
  └── infrastructure/
      └── deployment.md

Why LLMs Love This

1. Context Boundaries: When an AI agent is working on the "Identity" service, you can feed it the entire identity/ folder. It gets the business logic (Markdown), the contract (OpenAPI), and the event triggers (AsyncAPI) without the noise of the payment system.
2. Explicit Contracts: The api.yaml is not a suggestion; it is the law. The frontend agent reads it to generate typed clients. The backend agent reads it to scaffold controllers.
3. Unified Vision: Infrastructure isn't an afterthought. It's defined alongside the domains it supports.

Introducing XeoContext

Structure is great, but we also need visualization to ensure our design makes sense to humans before we hand it off to machines.

XeoContext is a tool designed specifically for this workflow. It visualizes your System Design content—organized in a Domain-Driven Structure—treating your local file system as the database.

It supports the holy trinity of modern system design in a single interface:

• Markdown for architecture decision records and business logic.
• OpenAPI for RESTful interfaces.
• AsyncAPI for event-driven architectures.

The "Clean Repo" Philosophy

One of the strongest features of XeoContext is how lightweight it is. It encourages a "Clean Repo" approach where your design repository contains zero application code.

All you need is your design files and a docker-compose.yaml.

services:
  xeocontext:
    image: xeost/xeocontext:latest
    ports:
      - "3000:3000"
    volumes:
      - ./content:/app/content

Running docker compose up gives you an instant, hot-reloading documentation site for your entire system architecture.

Conclusion

If we want AI to build complex, reliable software, we must stop asking it to invent the system on the fly. We must provide a blueprint.

By centralizing your System Design in a structured, domain-driven repository and using tools like XeoContext to visualize and validate it, you ensure that every line of code generated—whether frontend, backend, or infra—sings in perfect harmony.

To examine a real-world example of this structure, check out the XeoContext Examples or dive into the Main Project README.