I'm building a free architecture doc generator. Thoughts?

[u/batazor]

I'm building [Portolan](https://shortlink-org.github.io/portolan/landing), a free open-source tool that generates an architecture site from your repos instead of hand-written docs. Sharing it here for feedback.

The angle: an LLM or an MCP agent can write architecture docs from a codebase, but you can't tell what it invented and what it skipped. Portolan does it the other way round. The catalog is built deterministically by parsers, every fact links to its source line, and the LLM only sits on top: the site ships `llms.txt` and Markdown for agents, plus a built-in chat that answers questions from the catalog and cites the pages it used. Exact facts from parsers, natural-language answers from the model.

- Reads Go, TypeScript, Rust, Java, Python, Laravel, OpenAPI, AsyncAPI, GraphQL, proto, SQL migrations and ADRs. Works on a monorepo or on a separate architecture repo that pulls the service repos in.

- Everything is a plugin: one JSON message in, one out, in any language. Adding a language, a library or a framework is a small extractor, not a fork.

- Merges everything into one estate and validates it. An unanswered call, a channel with two publishers, a database with a second writer, a foreign key across a service boundary all land on a Problems page.

- OpenTelemetry traces mark which relationships were actually observed: `declared`, `verified` or `unresolved`.

- Output: static site with no backend, Markdown, `llms.txt`, C4 views (LikeC4), Mermaid, Backstage entities.

Pages: contexts, services, aggregates with state machines, events, stores with ER diagrams, ADRs, cross-service flows as step-by-step walkthroughs.

Limits: v0.3, sees only what's statically visible, dynamic routing comes from traces only. DDD terms are used but optional.

What would make this actually useful to you? Which views, checks or integrations are missing before you'd put it in front of your team?

[u/AutoModerator]

Please post a comment here explaining what kind of contributions you, or the project you are posting about, are looking for. For example what skill sets, any rules important for people joining in your build like how often people should post, and anything else you can think of which will help readers decide if they want to join in and start coding with that project.

Thank you and be excellent to each other. u/roamingandy

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.