LLMs for Architectural Refactoring: An Exploratory study on Monoliths to Microservices

# LLMs for Architectural Refactoring: An Exploratory study on Monoliths to Microservices This repository combines:- The decomposition generation pipeline (summaries, artifacts, decomposition extraction) for 4 monolith repositories.- The metrics artifact pipeline (`metrics/scripts`) for evaluating decompositions.- A Rust + Trunk web visualization (`web-visualization`). For sanitized artifact-only usage, the core subset is:1. Metric calculation pipeline (`metrics/scripts`)2. Web visualization artifact (`web-visualization`) This README is the single canonical guide for both the larger decomposition workflow and custom metrics/web artifact usage. This repository is a replication package: some metrics and analyses available here are broader than the subset reported in `paper.pdf`. The package is intended to reproduce reported results and enable deeper follow-up analysis. For installation and environment setup, see `INSTALL.md`. ## NoteThe artifact_web that is the web-view is for easier process for the reviewers to verify the replication package has been made just a day before the submission of artifact to make the review process easier, its still in early phases so please mind the bugs. ## Paper Authors - Aneesh Sambu (`sambu.aneesh@research.iiit.ac.in`)- Roberta Capuano (`roberta.capuano@univaq.it`)- Eoan O'Dea (`eoan.odea@graduate.univaq.it`)- Henry Muccini (`henry.muccini@univaq.it`)- Karthik Vaidyanathan (`karthik.vaidyanathan@iiit.ac.in`) ## Contact For any queries, contact: `sambu.aneesh@research.iiit.ac.in` ## Zenodo DOI `10.5281/zenodo.18622108` ## License This repository is licensed under the MIT License (`LICENSE`). Note: several bundled case-study systems and datasets include their own upstream licenses inside their respective folders; those remain under their original terms. --- ## Interactive Results Visualization For interactive analysis and comparison of decomposition results, visit: [llms4micro.vercel.app](https://llms4micro.vercel.app) The web interface provides:- Multi-repository comparison: view results for all 4 repositories side-by-side.- Dynamic visualizations: bar charts (ranking), radar charts (multi-metric tradeoffs), and tables.- Real-time filtering: include/exclude tools, LLM models, or decomposition strategies.- Custom aggregation: define which LLM strategies contribute to average scores. Use the interface to identify best-performing approaches, compare LLM consistency across metrics (MoJoFM, CMod, BCP, etc.), and analyze both per-repository and global performance. Note: metric calculation scripts are adapted from the [Microservice Decomposition Tool Study](https://resess.github.io/artifacts/MicroserviceToolStudy/docs/metrics.html). --- ## Prerequisites - Linux/macOS shell (`bash`/`zsh`)- Python 3.12+- `uv`- Rust toolchain (`rustup`) + `wasm32-unknown-unknown` target- `trunk` ### Install `uv` ```bashcurl -LsSf https://astral.sh/uv/install.sh | sh``` Alternative: ```bashpython3 -m pip install --user uv``` Check: ```bashuv --version``` ### Install Rust + Trunk ```bashcurl https://sh.rustup.rs -sSf | sh -s -- -ysource "$HOME/.cargo/env"rustup target add wasm32-unknown-unknowncargo install trunk``` Check: ```bashrustc --versiontrunk --version``` --- ## Single Unified `uv` Setup (Root Only) This repo now uses one Python environment and one lockfile at the repository root. ```bashuv venv .venvuv sync --no-install-project``` Use all Python commands from repo root as: ```bashuv run python ``` Some legacy metrics scripts rely on their own working directory (for relative `./data/...` paths), so those commands in this README use `cd metrics/scripts` (or `cd metrics/scripts/data/metrics`) before `uv run`. --- ## LLM Provider Configuration All tools support multiple LLM providers through a centralized configuration system.This is only required when running generation steps that call LLM APIs. Gemini:```bashexport LLM_PROVIDER=GEMINIexport GEMINI_API_KEY=your_key_here``` OpenAI:```bashexport LLM_PROVIDER=OPENAIexport OPENAI_API_KEY=your_key_here``` DeepSeek:```bashexport LLM_PROVIDER=DEEPSEEKexport DEEPSEEK_API_KEY=your_key_here``` GLM:```bashexport LLM_PROVIDER=GLMexport GLM_API_KEY=your_key_here``` Default provider is `GEMINI` if not specified. Models used:- Gemini: `gemini-2.5-pro`- OpenAI: `gpt-5`- DeepSeek: `deepseek-reasoner`- GLM: `glm-4.6` See `tools/README.md` for detailed provider/config options. --- ## Cost-Safe Default (Recommended) You do **not** need to regenerate chunk summaries / AI summaries / artifacts to evaluate this package. - The repository already includes generated decomposition inputs required for metric evaluation.- You can run metrics and web-data verification with **no API keys** and **no LLM cost**.- LLM/API keys are only needed if you intentionally rerun generation workflows (`Generate` stage in the website or equivalent manual scripts). --- ## Directory Structure ```textmonoliths/├── /│ ├── graph-artifacts/│ │ └── -class-dependency.json # Dependency graph│ ├── gitingest.txt # Full repository ingest│ ├── chunks/│ │ └── / # Split gitingest files (30k, 50k, 80k)│ │ └── *.txt│ └── summaries/│ └── / # e.g., gemini-2.5-pro, gpt-5│ ├── /│ │ ├── summary_chunk_ .txt│ │ ├── tokens_chunk_ .json│ │ ├── concat_summary.txt│ │ ├── ai_summary.txt│ │ ├── tokens_ai_summary.json│ │ ├── artifacts_concat/│ │ └── artifacts_ai/│ ├── full_repo/│ │ └── artifacts/│ └── hierarchical/│ ├── summary.md│ └── artifacts/ metrics/scripts/├── main.py # Metrics pipeline entrypoint├── manage_decompositions.py # Manifest/scaffold helper└── data/ ├── decompositions/manifest.json └── metrics/ ├── metrics.csv ├── mojofm.csv ├── entropy.csv ├── statistics.csv └── web_data.json web-visualization/└── web_data.json + Trunk app artifact_web/├── app.py # FastAPI orchestration backend└── static/ # Brutalist SPA frontend``` Key components:- `graph-artifacts/`: dependency graphs for each repository.- `gitingest.txt`: full repository ingest.- `chunks/ /`: split ingest files (`30k`, `50k`, `80k`).- `summaries/ /`: model-specific summary/artifact outputs.- `full_repo/artifacts/`: artifacts from full repository ingest.- `hierarchical/`: hierarchical summaries and artifacts.- `metrics/scripts`: decomposition metric calculation and table generation.- `web-visualization`: Rust/Trunk visualization app.- `artifact_web`: all-in-one web control plane for this repository. --- ## Recommended: Use the Web Control Plane Run: ```bashuv run python -m artifact_web.app``` Open: ```texthttp://127.0.0.1:8787``` The web control plane provides:- End-to-end pipeline orchestration across `tools/`, `metrics/scripts`, and `web-visualization`.- Staged, guided workflow views (`Setup`, `Generate`, `Evaluate`, `Publish`, `Full`, `Advanced`) with run recipes.- Profile-driven execution (repo/model/chunk/strategy/concurrency/import behavior).- Intelligent skip logic for already-generated outputs (optional force rerun).- Auto-bootstrap for root `uv` environment; `trunk`/wasm are checked only when web build/serve actions run.- Dashboard for first-time onboarding + quick actions.- Full explorer with filters, bucket enable/disable/delete, decomposition stats, and JSON preview.- Custom decomposition scaffold/import form in the UI.- Live logs and live progress tracking via SSE.- Hash verification between metrics `web_data.json` and web app `web_data.json`. --- ## Repositories and Chunks Used in Batch Commands ```bashREPOS=("7ep-demo" "jpetstore-6" "PartsUnlimitedMRP" "spring-petclinic")CHUNKS=("30k" "50k" "80k")``` --- ## Batch Pipeline: `gemini-2.5-pro` ```bashMODEL="gemini-2.5-pro"``` ### 1) Generate all chunk summaries ```bashfor repo in "${REPOS[@]}"; do for chunk in "${CHUNKS[@]}"; do uv run python tools/summarizer/chunk_summarizer.py \ --input-dir "monoliths/${repo}/chunks/${chunk}" \ --output-dir "monoliths/${repo}/summaries/${MODEL}/${chunk}" & donedonewait``` ### 2) Merge all summaries ```bashfor repo in "${REPOS[@]}"; do for chunk in "${CHUNKS[@]}"; do uv run python tools/summarizer/merge_summaries.py \ --input-dir "monoliths/${repo}/summaries/${MODEL}/${chunk}" & donedonewait``` ### 3) Generate artifacts (concat + ai) and full repo artifacts ```bashfor repo in "${REPOS[@]}"; do for chunk in "${CHUNKS[@]}"; do uv run python tools/generate_artifacts.py \ --input "monoliths/${repo}/summaries/${MODEL}/${chunk}/concat_summary.txt" \ --output "monoliths/${repo}/summaries/${MODEL}/${chunk}/artifacts_concat" & uv run python tools/generate_artifacts.py \ --input "monoliths/${repo}/summaries/${MODEL}/${chunk}/ai_summary.txt" \ --output "monoliths/${repo}/summaries/${MODEL}/${chunk}/artifacts_ai" & donedonewait for repo in "${REPOS[@]}"; do uv run python tools/generate_artifacts.py \ --input "monoliths/${repo}/gitingest.txt" \ --output "monoliths/${repo}/summaries/${MODEL}/full_repo/artifacts" &donewait``` ### 4) Generate decompositions from artifacts ```bashfor repo in "${REPOS[@]}"; do graph="monoliths/${repo}/graph-artifacts/${repo}-class-dependency.json" for chunk in "${CHUNKS[@]}"; do uv run python tools/decompose_artifacts.py \ --input-dir "monoliths/${repo}/summaries/${MODEL}/${chunk}/artifacts_ai/" \ --dependency-graph "${graph}" & uv run python tools/decompose_artifacts.py \ --input-dir "monoliths/${repo}/summaries/${MODEL}/${chunk}/artifacts_conc