Software architecture

Software Architecture

Use this skill before coding when the main risk is not syntax, but choosing the wrong structure.

Goal

Increase implementation success rate by deciding the shape of the solution before writing too much code.

Focus on:

1. boundaries
2. responsibilities
3. data flow
4. state flow
5. module seams
6. failure modes
7. simplest structure that will hold

Core Rules

1. Start from the job to be done

Before proposing structure, restate:

• what the feature/system must do
• what inputs it receives
• what outputs it produces
• what constraints matter
• what should stay out of scope

Do not start with patterns or layers before the problem is clear.

2. Prefer simple structure first

Choose the simplest structure that can support the current task.

Avoid premature:

• abstraction
• indirection
• plugin systems
• generic frameworks
• splitting into too many files/modules too early

Add complexity only when it clearly reduces future failure.

3. Separate responsibilities explicitly

Identify which parts are responsible for:

• input gathering
• parsing/validation
• business logic
• state updates
• rendering/output
• I/O or external effects
• error handling

If one unit is doing too many of these at once, the design is probably too tangled.

4. Design around seams that are testable

Prefer boundaries that make it easier to:

• test logic without UI
• test transformations without network/file I/O
• replace implementation details later
• localize bugs to one layer or module

5. Make data flow visible

Clarify:

• where data enters
• how it is transformed
• where state changes
• what side effects happen
• what the final output depends on

If the flow cannot be explained simply, the structure is likely too complex.

6. Consider failure modes early

Before coding, ask:

• what can be missing, invalid, stale, slow, or out of order?
• where should errors be caught?
• what should happen on partial failure?
• what assumptions may later break?

Minis-Specific Workflow

Shell-first planning

Use shell/file inspection to:

• review current project structure
• inspect existing module layout
• find similar code paths
• understand current test coverage
• locate where new logic should fit instead of creating parallel structure unnecessarily

Browser-aware architecture

For web or HTML tools, distinguish:

• UI rendering
• browser state
• app state
• event handling
• persistence or backend interactions

Do not let UI code absorb business logic unless the app is truly tiny.

Small-project bias

On Minis, many projects are scripts, utilities, or compact web tools.

Bias toward:

• fewer moving parts
• fewer files when practical
• simple interfaces
• clear data flow over textbook layering

Planning Sequence

Use this order:

1. Restate the problem and scope.
2. Identify inputs, outputs, and constraints.
3. Identify major responsibilities.
4. Sketch the data flow and state flow.
5. Decide where side effects live.
6. Choose the smallest module/file split that keeps the code understandable.
7. Identify what should be directly testable.
8. Call out likely failure modes or future pressure points.
9. Only then start implementation.

Common Design Mistakes

Watch for:

• business logic mixed into UI handlers
• parsing, validation, and side effects all in one function
• too many abstractions for a small tool
• hidden state shared across unrelated parts
• file/module splits that add confusion rather than clarity
• no clear place for errors to be handled
• code that cannot be tested without full app startup
• introducing a framework pattern without a real need

Output Style

Prefer concise architecture outputs such as:

• 3–7 responsibility bullets
• a small module/file plan
• a simple data-flow outline
• a short list of failure modes
• one clear recommendation for where to start coding

Integration with Other Skills

• Use test-driven-development after the structure is clear and you want to implement safely.
• Use root-cause-tracing if the current design already exists and failures suggest the structure may be wrong.
• Use webapp-testing when the architecture affects browser-visible behavior or UI state.
• Use finishing-a-development-branch once implementation is complete and needs cleanup and handoff.

Completion Checklist

Before calling the architecture plan good enough, check:

• Is the scope clearly bounded?
• Are responsibilities separated clearly enough?
• Is the data/state flow understandable?
• Is the structure simpler than the overengineered alternative?
• Are side effects isolated enough?
• Is the code likely to be testable in pieces?
• Is there a clear first implementation step?

Response Template

• Problem/scope:
• Inputs/outputs:
• Main responsibilities:
• Proposed structure:
• Data/state flow:
• Side effects:
• Failure modes:
• First implementation step:

Example Triggers

• "Before coding this, help me design the structure."
• "What is the simplest architecture for this feature?"
• "Split this tool into clean responsibilities before implementation."
• "How should this web app separate UI, state, and logic?"
• "Help me avoid overengineering this project."