A few days ago, I posted this on X:
“I keep running into the same question in multi-repo systems: should architecture docs live per repo, or at the system level?”
Feels like both come with different tradeoffs…
This sparked a great conversation I had with Grok (yes, xAI’s), and Grok challenged me to test it hands-on with QEEK AI. I threw the classic Sock Shop microservices demo at it (10+ repos, polyglot languages, mixed databases, and orchestration across service boundaries).
Alpha experiment
This isn’t a benchmark. It’s a quick “does this doc style hold up under multi-repo complexity?” test, using generated docs as evidence.
The hero test: Sock Shop multi-repo deep dive
Sock Shop is a perfect stress test: distributed e-commerce services (carts, users, catalogue, orders, payment, shipping, front-end) split into separate repos. The real value is in the connections: flows, dependencies, and trade-offs across boundaries.
Key takeaway
System-level docs excel when the value is in connections. Per-repo docs for Sock Shop services felt a bit redundant. Individual repos are small and only make sense in the context of the whole. We generated repo-level docs anyway so you can judge it for yourself.
Single-repo contrast: FastAPI orientation
We also tested on a popular single-repo project: the FastAPI framework and its official full-stack template (the reference app that shows how to build real applications with it).
In under a minute, QEEK generated:
- →Architecture Overview (system-level map)
- →Application Flows (end-to-end user journeys)
- →Directory Structure (clean map + purposes)
- →Tech Stack (languages, deps, testing, patterns)
- →Project Overview (purpose, philosophy, flow)
This combo shows how QEEK connects framework-level patterns to concrete implementation, perfect for quick orientation and feeding to Cursor/Windsurf agents.
Per-repo vs system-level: what actually worked
- →Individual repos are big/complex and you onboard one piece at a time.
- →You need runbooks, local dev notes, and “where to edit now.”
- →The value is in flows and dependencies across boundaries (orchestration, failure modes).
- →Services are small and uniform. Per-repo architecture docs would be redundant.
Most teams end up hybrid: system docs for the “why it all fits,” repo docs for the “how to ship this part.” In our tests, guide-style (flows + maps) built understanding faster than encyclopedia-style lists, for humans and for agents.
Related: Guide vs Encyclopedia.
What’s next for QEEK
These tests confirmed our direction: layered, intent-driven, cost-aware code intelligence. Still alpha, expect weirdness, but already useful in under a minute, fully client-side.
We’d love your take: does this match your multi-repo pains? What trade-offs did we miss? Try it on your repo and roast the output.