Skip to content

docs: draw.io architecture, class, use-case, and sequence diagrams #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
getdownandcode merged 1 commit into from
Sep 7, 2026
Merged

docs: draw.io architecture, class, use-case, and sequence diagrams #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 0 additions & 8 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,12 +69,4 @@ Thumbs.db
#md files
plan.md

#docs
docs/architecture.visual-check.json
docs/architecture.html
docs/architecture.visual-check.1440x900.dark.png
docs/architecture.visual-check.1440x900.light.png
docs/architecture.visual-check.2048x1320.dark.png
docs/architecture.visual-check.html

gitmate.architecture.json
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,15 @@ uv run gitmate config set model gemini-flash

`commit`, `pr-summary`, `changelog`, and `doc` are stubbed until their phases
land — see `AGENTS.md` and the phased roadmap for details.

## Diagrams

Editable draw.io sources plus publishable PNG exports (open the `.drawio`
files in the draw.io desktop app to edit):

| Diagram | Source | Export |
|---|---|---|
| System architecture (Phases 0–8, gemini-3.5-flash-lite) | [`docs/architecture.drawio`](docs/architecture.drawio) | [`docs/architecture.png`](docs/architecture.png) |
| Phase 0 class diagram (`config.py`, `cli.py`) | [`docs/class-diagram.drawio`](docs/class-diagram.drawio) | [`docs/class-diagram.png`](docs/class-diagram.png) |
| Use cases (implemented + planned) | [`docs/use-case.drawio`](docs/use-case.drawio) | [`docs/use-case.png`](docs/use-case.png) |
| `config` command sequences | [`docs/sequence.drawio`](docs/sequence.drawio) | [`docs/sequence.png`](docs/sequence.png) |
149 changes: 149 additions & 0 deletions docs/architecture.drawio
View file
Open in desktop

Large diffs are not rendered by default.

Binary file added docs/architecture.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
101 changes: 101 additions & 0 deletions docs/class-diagram.drawio
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
<diagram name="class-diagram">
<mxGraphModel dx="1000" dy="700" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1280" pageHeight="920" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="title" value="gitmate — Phase 0 class diagram" style="text;html=1;align=left;verticalAlign=middle;fontStyle=1;fontSize=22;" vertex="1" parent="1">
<mxGeometry x="40" y="20" width="700" height="34" as="geometry"/>
</mxCell>
<mxCell id="subtitle" value="src/gitmate/config.py + cli.py · commands carry no logic; all I/O behind substitutable interfaces" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;fontColor=#555555;" vertex="1" parent="1">
<mxGeometry x="40" y="56" width="1000" height="22" as="geometry"/>
</mxCell>
<mxCell id="cfg_t" value="&#171;dataclass&#187;&lt;br/&gt;GitmateConfig" style="rounded=1;whiteSpace=wrap;html=1;align=center;fontStyle=1;fontSize=13;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="60" y="90" width="220" height="48" as="geometry"/>
</mxCell>
<mxCell id="cfg_b" value="+ model: str&lt;br/&gt;+ commit_style: str&lt;br/&gt;+ budget_cap_usd: float | None" style="rounded=0;whiteSpace=wrap;html=1;align=left;verticalAlign=top;fontSize=12;spacingLeft=8;spacingTop=6;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="60" y="138" width="220" height="84" as="geometry"/>
</mxCell>
<mxCell id="ss_t" value="&#171;protocol&#187;&lt;br/&gt;SecretStore" style="rounded=1;whiteSpace=wrap;html=1;align=center;fontStyle=1;fontSize=13;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
<mxGeometry x="500" y="90" width="220" height="48" as="geometry"/>
</mxCell>
<mxCell id="ss_b" value="+ set_secret(account, secret)&lt;br/&gt;+ get_secret(account): str | None" style="rounded=0;whiteSpace=wrap;html=1;align=left;verticalAlign=top;fontSize=12;spacingLeft=8;spacingTop=6;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
<mxGeometry x="500" y="138" width="220" height="64" as="geometry"/>
</mxCell>
<mxCell id="err_t" value="ConfigError&lt;br/&gt;&#171;extends Exception&#187;" style="rounded=1;whiteSpace=wrap;html=1;align=center;fontStyle=1;fontSize=13;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
<mxGeometry x="920" y="90" width="220" height="48" as="geometry"/>
</mxCell>
<mxCell id="err_b" value="raised by load_config()&lt;br/&gt;on unreadable TOML" style="rounded=0;whiteSpace=wrap;html=1;align=left;verticalAlign=top;fontSize=12;spacingLeft=8;spacingTop=6;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
<mxGeometry x="920" y="138" width="220" height="64" as="geometry"/>
</mxCell>
<mxCell id="kr_t" value="KeyringSecretStore" style="rounded=1;whiteSpace=wrap;html=1;align=center;fontStyle=1;fontSize=13;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="280" y="380" width="220" height="40" as="geometry"/>
</mxCell>
<mxCell id="kr_b" value="+ set_secret(...) → OS Keychain&lt;br/&gt;+ get_secret(...) → str | None&lt;br/&gt;— production store" style="rounded=0;whiteSpace=wrap;html=1;align=left;verticalAlign=top;fontSize=12;spacingLeft=8;spacingTop=6;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="280" y="420" width="220" height="92" as="geometry"/>
</mxCell>
<mxCell id="mem_t" value="InMemorySecretStore" style="rounded=1;whiteSpace=wrap;html=1;align=center;fontStyle=1;fontSize=13;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="740" y="380" width="220" height="40" as="geometry"/>
</mxCell>
<mxCell id="mem_b" value="− _secrets: dict&lt;br/&gt;+ set_secret(...)&lt;br/&gt;+ get_secret(...)&lt;br/&gt;— tests only, no OS store" style="rounded=0;whiteSpace=wrap;html=1;align=left;verticalAlign=top;fontSize=12;spacingLeft=8;spacingTop=6;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="740" y="420" width="220" height="112" as="geometry"/>
</mxCell>
<mxCell id="cli_t" value="cli — Typer app&lt;br/&gt;&#171;commands only, no logic&#187;" style="rounded=1;whiteSpace=wrap;html=1;align=center;fontStyle=1;fontSize=13;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="440" y="620" width="340" height="48" as="geometry"/>
</mxCell>
<mxCell id="cli_b" value="commit() · pr-summary() · changelog() · doc()&lt;br/&gt;config set-key() / show() / set()&lt;br/&gt;— uses SecretStore + GitmateConfig" style="rounded=0;whiteSpace=wrap;html=1;align=left;verticalAlign=top;fontSize=12;spacingLeft=8;spacingTop=6;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
<mxGeometry x="440" y="668" width="340" height="104" as="geometry"/>
</mxCell>
<mxCell id="legend" value="Legend" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#666666;verticalAlign=top;fontStyle=1;fontSize=13;" vertex="1" parent="1">
<mxGeometry x="40" y="830" width="900" height="60" as="geometry"/>
</mxCell>
<mxCell id="leg1" value="" style="rounded=0;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="legend">
<mxGeometry x="10" y="30" width="30" height="16" as="geometry"/>
</mxCell>
<mxCell id="leg1t" value="Class" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;" vertex="1" parent="legend">
<mxGeometry x="50" y="28" width="200" height="20" as="geometry"/>
</mxCell>
<mxCell id="leg2" value="" style="rounded=0;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="legend">
<mxGeometry x="300" y="30" width="30" height="16" as="geometry"/>
</mxCell>
<mxCell id="leg2t" value="Interface (protocol)" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;" vertex="1" parent="legend">
<mxGeometry x="340" y="28" width="200" height="20" as="geometry"/>
</mxCell>
<mxCell id="leg3" value="" style="rounded=0;html=1;fillColor=none;strokeColor=#666666;dashed=1;" vertex="1" parent="legend">
<mxGeometry x="590" y="30" width="30" height="16" as="geometry"/>
</mxCell>
<mxCell id="leg3t" value="Implements / uses (dashed)" style="text;html=1;align=left;verticalAlign=middle;fontSize=12;" vertex="1" parent="legend">
<mxGeometry x="630" y="28" width="250" height="20" as="geometry"/>
</mxCell>
<mxCell id="e_kr" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;endArrow=block;endFill=0;dashed=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="kr_t" target="ss_b">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="390" y="300"/>
<mxPoint x="610" y="300"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="e_mem" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;endArrow=block;endFill=0;dashed=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.86;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="mem_t" target="ss_b">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="850" y="300"/>
<mxPoint x="690" y="300"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="e_cli_ss" value="uses" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;fontSize=12;labelBackgroundColor=#ffffff;endArrow=open;endFill=0;dashed=1;exitX=0.56;exitY=0;exitDx=0;exitDy=0;entryX=0.59;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="cli_t" target="ss_b">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="e_cli_cfg" value="uses" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;fontSize=12;labelBackgroundColor=#ffffff;endArrow=open;endFill=0;dashed=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="cli_b" target="cfg_b">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="170" y="720"/>
<mxPoint x="170" y="222"/>
</Array>
</mxGeometry>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
Binary file added docs/class-diagram.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
79 changes: 79 additions & 0 deletions docs/sequence.drawio
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
<diagram id="seqlayout" name="config commands">
<mxGraphModel dx="800" dy="600" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="title" value="gitmate config commands — set-key and show (Phase 0)" style="text;html=1;align=left;verticalAlign=middle;fontStyle=1;fontSize=18;" vertex="1" parent="1">
<mxGeometry x="40" y="4" width="620" height="28" as="geometry"/>
</mxCell>
<mxCell id="dev" value="Developer" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;size=40;" vertex="1" parent="1">
<mxGeometry x="40" y="40" width="100" height="730" as="geometry"/>
</mxCell>
<mxCell id="cli" value="gitmate CLI" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;size=40;" vertex="1" parent="1">
<mxGeometry x="240" y="40" width="100" height="730" as="geometry"/>
</mxCell>
<mxCell id="cfg" value="config.py" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;size=40;" vertex="1" parent="1">
<mxGeometry x="440" y="40" width="100" height="730" as="geometry"/>
</mxCell>
<mxCell id="key" value="OS Keychain" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;dropTarget=0;collapsible=0;recursiveResize=0;outlineConnect=0;portConstraint=eastwest;size=40;" vertex="1" parent="1">
<mxGeometry x="640" y="40" width="100" height="730" as="geometry"/>
</mxCell>
<mxCell id="act0" value="" style="html=1;points=[];perimeter=orthogonalPerimeter;outlineConnect=0;fillColor=#ffffff;" vertex="1" parent="key">
<mxGeometry x="45" y="210" width="10" height="50" as="geometry"/>
</mxCell>
<mxCell id="act1" value="" style="html=1;points=[];perimeter=orthogonalPerimeter;outlineConnect=0;fillColor=#ffffff;" vertex="1" parent="cli">
<mxGeometry x="45" y="90" width="10" height="280" as="geometry"/>
</mxCell>
<mxCell id="act2" value="" style="html=1;points=[];perimeter=orthogonalPerimeter;outlineConnect=0;fillColor=#ffffff;" vertex="1" parent="cfg">
<mxGeometry x="45" y="470" width="10" height="50" as="geometry"/>
</mxCell>
<mxCell id="act3" value="" style="html=1;points=[];perimeter=orthogonalPerimeter;outlineConnect=0;fillColor=#ffffff;" vertex="1" parent="key">
<mxGeometry x="45" y="570" width="10" height="50" as="geometry"/>
</mxCell>
<mxCell id="act4" value="" style="html=1;points=[];perimeter=orthogonalPerimeter;outlineConnect=0;fillColor=#ffffff;" vertex="1" parent="cli">
<mxGeometry x="45" y="420" width="10" height="250" as="geometry"/>
</mxCell>
<mxCell id="m0" value="config set-key" style="html=1;verticalAlign=bottom;endArrow=block;curved=0;rounded=0;exitX=0.5;exitY=0.1184;entryX=0;entryY=0.0;" edge="1" parent="1" source="dev" target="act1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m1" value="prompt + confirm (hidden)" style="html=1;verticalAlign=bottom;endArrow=block;curved=0;rounded=0;exitX=1;exitY=0.1786;entryX=1;entryY=0.2857;" edge="1" parent="1" source="act1" target="act1">
<mxGeometry relative="1" as="geometry">
<Array as="points"><mxPoint x="350" y="180"/><mxPoint x="350" y="210"/></Array>
</mxGeometry>
</mxCell>
<mxCell id="m2" value="set_secret(api-key)" style="html=1;verticalAlign=bottom;endArrow=block;curved=0;rounded=0;exitX=1;exitY=0.4286;entryX=0;entryY=0.0;" edge="1" parent="1" source="act1" target="act0">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m3" value="OK" style="html=1;verticalAlign=bottom;endArrow=open;dashed=1;curved=0;rounded=0;strokeColor=#999999;fontColor=#999999;exitX=0;exitY=1.0;entryX=1;entryY=0.6071;" edge="1" parent="1" source="act0" target="act1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="note4" value="key never written to disk" style="shape=note;whiteSpace=wrap;html=1;size=14;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
<mxGeometry x="710" y="330" width="140" height="40" as="geometry"/>
</mxCell>
<mxCell id="m5" value="API key saved" style="html=1;verticalAlign=bottom;endArrow=open;dashed=1;curved=0;rounded=0;strokeColor=#999999;fontColor=#999999;exitX=0;exitY=1.0;entryX=0.5;entryY=0.4868;" edge="1" parent="1" source="act1" target="dev">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m6" value="config show" style="html=1;verticalAlign=bottom;endArrow=block;curved=0;rounded=0;exitX=0.5;exitY=0.5526;entryX=0;entryY=0.0;" edge="1" parent="1" source="dev" target="act4">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m7" value="load_config()" style="html=1;verticalAlign=bottom;endArrow=block;curved=0;rounded=0;exitX=1;exitY=0.2;entryX=0;entryY=0.0;" edge="1" parent="1" source="act4" target="act2">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m8" value="GitmateConfig" style="html=1;verticalAlign=bottom;endArrow=open;dashed=1;curved=0;rounded=0;strokeColor=#999999;fontColor=#999999;exitX=0;exitY=1.0;entryX=1;entryY=0.4;" edge="1" parent="1" source="act2" target="act4">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m9" value="get_secret(api-key)" style="html=1;verticalAlign=bottom;endArrow=block;curved=0;rounded=0;exitX=1;exitY=0.6;entryX=0;entryY=0.0;" edge="1" parent="1" source="act4" target="act3">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m10" value="secret | None" style="html=1;verticalAlign=bottom;endArrow=open;dashed=1;curved=0;rounded=0;strokeColor=#999999;fontColor=#999999;exitX=0;exitY=1.0;entryX=1;entryY=0.8;" edge="1" parent="1" source="act3" target="act4">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="m11" value="settings table (no secret)" style="html=1;verticalAlign=bottom;endArrow=open;dashed=1;curved=0;rounded=0;strokeColor=#999999;fontColor=#999999;exitX=0;exitY=1.0;entryX=0.5;entryY=0.8816;" edge="1" parent="1" source="act4" target="dev">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
Binary file added docs/sequence.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading