Standard for creating technical documentation in this repository. Use this when writing new documentation in docs/ to ensure consistent hierarchy and formatting.

2026-02-022

mermaid-diagrams

FullFran/Hybrid-RAG-example

Expert guidance on creating accurate, visually polished Mermaid diagrams for architecture documentation.

2026-02-022

mongodb

FullFran/Hybrid-RAG-example

Expert guidance on MongoDB implementation for RAG, including aggregation pipelines and search patterns.

2026-02-022

pydantic-ai

FullFran/Hybrid-RAG-example

Expert guidance on building agents and tools with Pydantic AI.

2026-02-022

name	software-architecture
description	Guide architecture decisions, document tradeoffs, and align designs with system goals and constraints.
license	MIT
metadata	{"author":"OpenCode","version":"1.0"}

Software Architecture

When to use

Making system-level decisions or introducing new subsystems.
Evaluating tradeoffs (performance, maintainability, scalability, cost).
Updating or creating architecture documentation in docs/.

Core guidance

Start from business goals and quality attributes.
Capture tradeoffs explicitly and keep decisions reversible when possible.
Prefer interfaces and contracts to isolate volatility.
Keep architecture diagrams and docs concise and up to date.

Do

Document major decisions in docs/ with rationale and constraints.
Use explicit interfaces in src/core/interfaces/ to decouple subsystems.
Keep new subsystems aligned with Clean Architecture layers.

Don't

Add cross-layer dependencies to "move faster".
Introduce new providers without contracts or tests.
Let docs drift from actual wiring in src/bootstrap.py.

Anti-patterns seen

Architecture decisions living only in code comments or PRs.
Skipping tradeoff discussion when introducing new infra.
Layer boundaries eroding due to quick fixes.

Repo anchors

docs/architecture.md
docs/framework-design.md (if present)
src/bootstrap.py

References

https://the-amazing-gentleman-programming-book.vercel.app/es/book/Chapter18_Software-Architecture