Monolith Decomposer: AI Principal Architect

Legacy monoliths kill innovation. We built Monolith Decomposer to put a Senior Architect in your pocket, turning months of architectural auditing into minutes of migration roadmap.

Comment

Inspiration

It started with a real scaling problem. We were building a highly successful Shopify plugin, but as we rapidly shipped new features, our clean codebase morphed into a tangled monolith. It became a "black box" that new developers simply couldn't decipher.

When we decided to refactor, we hit a wall. As the lead developers, we were the only ones who understood the system's deep dependencies. Standard AI assistants were great at writing functions, but they were blind to the architecture. Manually mapping the file structures and untangling the database took us days to plan and weeks to align the team. We realized developers don't just need a coding assistant they need an AI Principal Architect to turn weeks of manual mapping into minutes of automated strategy.

What it does

Monolith Decomposer acts as your AI Principal Architect. You give it a monolithic repository, and it performs a deep-tissue architectural scan to output a complete DevSecOps blueprint:

  • Domain-Driven Discovery: Identifies Bounded Contexts by analyzing static code and runtime dependencies.
  • Automated Schema Partitioning: Intelligently maps your monolithic database fields into specific microservice schemas (e.g., PostgreSQL, Redis, S3).
  • Strangler Fig Roadmaps: Generates a bespoke, week-by-week migration plan ensuring zero-downtime.
  • Infrastructure-as-Code: Outputs ready-to-use FastAPI contracts, Docker-Compose files, and deployment architectures tailored for GitLab workflows.

How we built it

Instead of relying on static templates, we built a Dynamic Structural Analysis engine.

  1. We parse the repository to extract the Abstract Syntax Tree (AST) and build a raw dependency graph.
  2. We apply graph clustering algorithms to group tightly coupled modules.
  3. We engineered a specialized LLM pipeline that analyzes this graph to identify the domain (e.g., E-commerce vs. ML Pipeline) and calculate the safest architectural boundaries.
  4. The engine then synthesizes these boundaries into a phased Strangler Fig migration strategy.

Challenges we ran into

  • Mapping "Data Gravity": The hardest part of microservices is the database. Teaching the AI to safely split a massive shared database without breaking relationships was incredibly difficult. We had to engineer prompts that could analyze SQL schemas and assign specific fields to new services.
  • Detecting Circular Dependencies: In complex repos (like our Image-Captioning ML test case), we found massive "hairballs" where modules constantly called each other. We had to train the system to flag these loops and propose event-driven architectures to break them.
  • Forcing Actionability: We didn't want a tool that just gave generic advice. Forcing the AI to generate precise, production-ready docker-compose.yml files and API contracts required rigorous prompt tuning and validation.

Accomplishments that we're proud of

We successfully transformed complex, real-world repositories into clean, multi-phase microservice architectures. In our Image-Captioning ML demo, the AI correctly realized that the Vocabulary and Dataset layers were the biggest bottlenecks, automatically placing them at the start of a custom 8-week Strangler Fig roadmap. Seeing our project provide Senior-level, highly specific architectural advice was a massive milestone for our team.

What we learned

We learned that architectural context is entirely different from code generation. Every monolith has its own unique "data gravity." By building this, we discovered how to prompt an LLM to think in Bounded Contexts ensuring that the suggested microservices are truly loosely coupled and independently scalable, rather than just the exact same monolith broken into smaller folders.

What's next for Monolith Decomposer: AI Principal Architect

Our vision is deep, native integration with the GitLab DevSecOps platform. Next, we plan to implement:

  • Auto-Issue Generation: Automatically converting the 8-week roadmap into populated GitLab Epics and Issues.
  • Pipeline Integration: Running Monolith Decomposer as a GitLab CI/CD job that flags Merge Requests if they introduce new circular dependencies or violate microservice boundaries.
  • Automated Scaffold PRs: Allowing the tool to automatically open a Merge Request with the base folder structure, Dockerfiles, and database schemas for the new microservices.

Built With

  • gitlab
  • gitlab-duo
  • llm
  • prompt
Share this project:

Updates