Software Architecture Documentation & Diagram Guide
Overview & Purpose
Software architecture documentation serves as the blueprint for your system, enabling team members to understand, maintain, and extend the codebase effectively. Good documentation reduces onboarding time, prevents architectural drift, and facilitates better decision-making.
One of the biggest things with documentation & code itself is developer intent. I will sound like a broken record on this, but developer intent is one of the single most important keys to producing a good codebase. Diagrams and documentation allow us to maintain our developer intent before we write any code.
Below we will define all of the core diagram types that are relevant to us. I would highly recommend using an LLM to create any documentation or diagrams where you can, for as long as you fully understand what is being created and stand behind that work. I (Christian) personally use Claude Code & Gemini to create a lot of my base documentation before i go and modify it to suite (unless i cant get my point across, to which i will then create it from scratch (: ). If you go down this route, please get it done in Draw.IO format not mermaid.
I am not expecting amazing fleshed out diagrams. We are just trying to weed out some of the known unknowns
Core Diagram Types
1. Entity Relationship Diagrams (ERDs)
Purpose: Show data relationships and structure
Example uses: For persistent data, save systems, character stats, inventory systems
Elements:
- Entities: Tables/Objects (rectangles)
- Attributes: Properties within entities
- Relationships: How entities connect (lines with cardinality)
- Cardinality: One-to-one, one-to-many, many-to-many
These are usually great for databases… Ive never made one for a game before, so i think this can be a little more custom as long as we are getting our point across. Showing intent is the most important factor for us.
2. UML Diagrams
Class Diagrams
Purpose: Show static structure of classes and their relationships Elements:
- Classes with attributes and methods
- Inheritance (triangular arrows)
- Composition/Aggregation (diamond arrows)
- Dependencies (dashed arrows)
Sequence Diagrams
Purpose: Show interactions over time Example uses: Battle turn flow, event processing, system initialization
State Diagrams
Purpose: Show state transitions Example uses: Battle states, game states, AI behavior states
Component Diagrams
Purpose: Show high-level system organization Example uses: Current architecture with more detail on interfaces
3. System Architecture Diagrams
C4 Model (Context, Container, Component, and Code)
Level 1 - Context: System in environment Level 2 - Container: High-level technology choices Level 3 - Component: Major building blocks Level 4 - Code: Classes and interfaces
Layered Architecture
Your current diagram is already layered - expand each layer:
- Infrastructure → Service details
- Game Systems → Component interactions
- Presentation → UI flow and rendering pipeline
Documentation Standards
Naming Conventions
- Consistent Terminology: Use the same terms across all diagrams
- Clear, Descriptive Names: Avoid abbreviations unless universally understood
Visual Standards
- Color Coding: Assign meaning to colors (e.g., red for critical paths, blue for data flow)
- Shape Consistency: Same shapes mean same things across diagrams
- Size Relationships: Larger elements = more important/complex
Metadata Requirements
Every diagram should include:
- Title & Purpose: What does this diagram show?
- Date Created/Modified: Version control
- Author: Who to ask questions
- Dependencies: What other diagrams relate to this
- Assumptions: What’s implied but not shown
Breakdown per domain
Core Infrastructure Layer
Game Systems Layer
Battle System
- Turn management system → State diagram & class diagram (optionally sequence diagram but i think the state diagram should cover the intent)
- Participant Management → Class diagram & a very very loose ERD. Im not expecting anything too crazy for the ERD. Keep it simple
- Undo Logic → Data flow diagram, Class Diagram & Component diagram. We need to clarify with Xander the design of the undo system & how it will work, what data we need to keep a hold of etc.
Unit Management
- Characters → Class Diagram & Component Diagram, State diagram … & potentially an ERD with items? unsure.
- Abilities system → Class diagram, State Diagram & Sequence diagram
- Animation System → State Diagram
- Items → ERD & Class diagram
Progression Systems
- Run management systems → State Diagram, Data flow diagram
- Character Upgrades → ERD, Class diagram, Sequence diagram.
- Permanent Unlocks → Component diagram (Need more info from Xander on how this works)
- Difficulty settings → Class diagram & Data flow diagram
- Proc Management → Sequence Diagram & Class diagram
World Generation
- Suburb map / Procedural levels → Class diagram, flowchart (for level generation steps), dataflow diagram & ERD
- Environmental objects → ERD & Class diagram
- Shop / Non battle rooms → State diagram, sequence diagram & ERD for pricing/inventory
Grid system
- Grid generation → ERD for grid + cell relationship, Class diagram and flowchart for the algorithm
- Grid movement → Sequence diagram, State diagram
- Cell state management → ERD for relationship between units, items and cell states. Class diagram.
- Tile formulas for attacks → Class diagram, flowchart… this one might be a bit funky & just require a document.
NPC AI systems (Requires further ideation)
- State machine/Behaviour tree → State diagram, definitions of nodes (This one is probably going to be difficult at the moment)
- Utility AI → Class diagram & flowcharts
- JPS Pathfinding (Uncomfirmed, requires further ideation before we start documentation)