Component & Code Level Diagrams

Component diagrams zoom into a single container and show its internal structure — controllers, services, repositories, and their dependencies. Code diagrams zoom further into a single component and show classes and interfaces. Most teams should draw component diagrams for complex containers and skip code diagrams entirely. Code diagrams are useful only for unusually complex components and are better generated from code than hand-drawn.

1. When to Draw Component Diagrams Draw component diagrams for containers with more than five major internal modules, containers that multiple teams work on simultaneously, and containers where the internal structure is non-obvious from the code. Do not draw component diagrams for simple CRUD services where the structure is predictable: controller → service → repository. The diagram should reveal structure that the reader cannot infer.
2. Component Diagram Design Show the major structural elements: controllers (entry points), services (business logic), repositories (data access), and external adapters (integrations). Label each with its responsibility. Draw dependencies as arrows from consumer to provider. The component diagram is a map of responsibility — it answers "if I need to change the order validation logic, which component do I modify?"
3. Code Level: Generate, Do Not Draw Code-level diagrams — class diagrams, interface hierarchies — should be generated from the code using tools that parse the AST and produce diagrams automatically. Hand-drawn code diagrams are stale the moment a class is renamed. Generated diagrams stay current because they are derived from the source of truth. Use them for complex domain models where visual representation aids understanding.