Solution Architecture Basics: Designing FDE Solutions & Architecture Diagrams

Architecture is the shape of a solution: what the pieces are, what each piece does, and how they talk to each other. This tutorial covers the vocabulary and patterns every solution is built from, shows how an FDE applies them under real engagement constraints, and finishes with the diagrams you'll use to think, present, and get the design approved.

Table of Contents

• What Is Solution Architecture?
• The Building Blocks of Every Solution
• Common Architecture Styles
• Architecture Decisions and Trade-offs
• What Makes FDE Solution Design Different
• The FDE Design Process, Step by Step
• Working Example: Designing an FDE Solution
• Architecture Diagrams: Why They Matter
• The Four Diagram Types You'll Use
• Reading and Writing Arrows
• Diagrams as Code: Mermaid
• Conventions That Make Diagrams Readable
• Best Practices

What Is Solution Architecture?

Solution architecture is the high-level structure of a system: its components, their responsibilities, and the connections between them. It answers questions like "where does the data live?", "what handles the requests?", and "what happens when something fails?" — before anyone writes code.

Architecture is not code. It's the set of decisions that are expensive to change later. Picking the wrong button color is a fix; picking the wrong database for your access patterns is a rebuild.

Why it matters: every hour spent on a bad structure multiplies into days of rework. A small amount of upfront design is the cheapest insurance in software.

The Building Blocks of Every Solution

Strip away the buzzwords and every solution is assembled from the same six kinds of pieces:

A useful mental model: data flows in one direction through these blocks — from the user, through services, into storage, and back. Most architecture work is deciding what each arrow looks like.

Common Architecture Styles

You'll meet four styles constantly. Each is a different answer to "how do we split up the work?"

Monolith — one application does everything.

[ Web UI + Business Logic + Data Access ]  →  [ Database ]

Simple to build, deploy, and debug. The right default for most FDE projects.

Client–Server / API-based — a frontend talks to a backend over HTTP.

[ Web / Mobile App ]  ⇄  [ REST API ]  ⇄  [ Database ]

The standard shape for anything with multiple client types or external integrations.

Microservices — many small services, each owning one job.

[ Orders service ] [ Billing service ] [ Notifications ]
        ↘                ↓                ↙
              [ message bus / APIs ]

Powerful at scale, expensive in complexity. Rarely justified for a single-customer build.

Event-driven — components react to events instead of calling each other directly.

[ Order placed ] → event bus → [ inventory updates ]
                              → [ email sends ]
                              → [ analytics records ]

Great for decoupling steps that don't need to happen at the same instant.

Note: these styles mix. A monolith with one event-driven pipeline is normal and healthy. Pick per problem, not per ideology.

Architecture Decisions and Trade-offs

Every architecture choice buys something and pays for something. There are no free lunches — only trade-offs you make consciously or by accident.

The professional move is stating the trade-off out loud: "We're using a queue here, which adds ~2 seconds of latency, so that a slow email provider can never block order confirmation."

Best Practice: when two designs both work, choose the boring one. Proven technology with a known failure mode beats clever technology every time in a customer engagement.

What Makes FDE Solution Design Different

An FDE designs under constraints a platform team never faces:

• Speed to value. The customer wants results in weeks, not quarters. The best architecture is the simplest one that meets the requirements.
• Existing systems. You almost never start from zero — the solution must fit around the customer's ERP, CRM, spreadsheets, and habits.
• Small team, often one. You will maintain what you design. That's a built-in argument against complexity.
• Requirements still moving. Early designs must tolerate change, because discovery keeps uncovering new facts.

These constraints point to a consistent FDE design philosophy: reuse before you build, configure before you code, and keep the architecture small enough to hold in one head.

The FDE Design Process, Step by Step

1. Start from the requirement map. The table from Tutorial 1 is your input — every solution piece must trace to a row.
2. Draw the data flow first. Where does data enter, where does it get transformed, where does it land? Components fall out of the flow, not the other way around.
3. Inventory what already exists. Customer systems, your company's platform, SaaS tools, open source. Reuse changes the shape of everything.
4. Choose the architecture style. Usually monolith or API-based for FDE work; add queues or events only where a real requirement demands it.
5. Place the cross-cutting concerns. Decide auth, logging, and monitoring now — bolting them on later is painful.
6. Stress-test on paper. Walk through failure scenarios ("what if the CRM API is down?") and growth scenarios ("what if volume triples?") before building.
7. Present it. One diagram, one page, plain language. The customer approves shapes, not specs.

Working Example: Designing an FDE Solution

The logistics case from Tutorial 1: drivers confirm deliveries on phones, the office sees status live, nothing is lost in dead zones, only dispatchers reassign, and volume triples at holidays.

Designing it step by step:

[ Driver phone app ]          [ Dispatcher dashboard ]
   (offline queue)                 (web app)
        │  syncs when online            │
        ▼                              ▼
[ Sync API ] ──────────────► [ Delivery service (monolith) ]
        │                              │
        ▼                              ▼
[ Deliveries DB ]            [ Roles & access control ]
        │
        ▼
[ Sync job → customer's ERP ]   (existing system — integrate, don't replace)

The decisions, with their trade-offs stated:

Read the diagram and you can see the philosophy: one service, one database, integration instead of replacement, and complexity only where a requirement forced it.

Architecture Diagrams: Why They Matter

A design only becomes real when someone else can see it. Diagrams do three jobs that text can't:

1. They expose gaps. A sentence can hide a missing step; an arrow can't. When you try to connect the boxes, you discover the piece you forgot.
2. They align people. Ten stakeholders will read one diagram in a meeting; none of them will read a 20-page spec.
3. They survive. Six months later, the diagram is still the fastest way to remember how the system works.

Best Practice: draw before you build. A diagram made during design is a thinking tool; a diagram made after launch is archaeology.

The Four Diagram Types You'll Use

You don't need the full UML catalog. Four types cover nearly every FDE situation:

Each one zooms into a different question. A good solution document has one of each, at most.

Component diagrams show the system's pieces and who talks to whom. Boxes are components; arrows are communication.

┌──────────────┐        ┌──────────────────┐        ┌──────────────┐
│  Mobile App  │───────▶│   Delivery API   │───────▶│ Deliveries DB│
└──────────────┘        └────────┬─────────┘        └──────────────┘
                                 │
                                 ▼
                        ┌──────────────────┐
                        │  Customer's ERP  │
                        └──────────────────┘

Name boxes by their job ("Delivery API"), not their technology ("Node server") — technology changes, jobs don't. Show only components that matter to the question being asked, and group related boxes inside a bigger box to show boundaries ("Customer's network", "Our cloud").

Data flow diagrams follow one thing: the data. Every arrow is labeled with what moves.

[Driver confirms] ──confirmation──▶ [Sync API] ──record──▶ [Deliveries DB]
                                        │
                                        ├──records──▶ [ERP sync job]
                                        │
                                        └──status──▶ [Office dashboard]

The discipline: label every arrow with the data it carries. Unlabeled arrows are where misunderstandings hide — "what exactly flows there?" is the question you want answered on paper, not in production. This is the best diagram type for integration design, because it forces you to name every handoff between systems.

Sequence diagrams show one scenario as a timeline of calls, read top to bottom. Each column is a participant.

Driver App  Sync API  Deliveries DB      ERP
   │              │                 │               │
   │── confirm ─────▶               │               │
   │              │── save ────────▶│               │
   │              │◀── ok ──────────│               │
   │◀── 200 OK ──────               │               │
   │              │── sync ────────────────────────▶│
   │              │◀── ack ─────────────────────────│

Use a sequence diagram when order matters: logins, payment flows, sync processes, anything with retries or timeouts. It's the only diagram type that shows time — and it's where you find the awkward questions ("what if the ERP doesn't answer?"). Draw the failure path too, or at least mark where it goes.

Deployment diagrams show where software physically runs: servers, clouds, networks, and the boundaries between them.

┌─────────── Customer network ───────────┐   ┌──────── Cloud ────────┐
│  [ Office dashboard ]  [ ERP server ]  │◀─▶│  [ API ]  [ Database ]│
└────────────────────────────────────────┘   └───────────────────────┘
              ▲
              │ internet
        [ Driver phones ]

This is the diagram for security and IT conversations: it shows what sits inside the customer's firewall, what sits in your cloud, and which arrows cross the boundary — exactly what their IT team will ask about.

Reading and Writing Arrows

Arrows carry most of a diagram's meaning, and most bad diagrams are bad because of sloppy arrows.

Two habits that prevent confusion:

• Arrow direction = direction of the request, not "importance" or "data ownership."
• If an arrow needs a paragraph to explain, you're missing a component. Split it.

Diagrams as Code: Mermaid

For anything that lives in documentation, write diagrams as text with Mermaid — it renders in GitHub, GitLab, Notion, and VS Code, and you can edit it like code.

flowchart LR
    A[Mobile App] -->|confirmations| B[Sync API]
    B --> C[(Deliveries DB)]
    B -->|sync| D[Customer ERP]
    B -->|status| E[Office Dashboard]

The same diagram as plain text:

flowchart LR
    A[Mobile App] -->|confirmations| B[Sync API]
    B --> C[(Deliveries DB)]
    B -->|webhook| D[Customer ERP]
    B -->|status| E[Office Dashboard]

Why text diagrams win in FDE work: they live in the repo, they get reviewed in pull requests, and updating one takes seconds. Save the drag-and-drop tools for the big presentation diagram.

Conventions That Make Diagrams Readable

• One diagram, one question. If a diagram answers "what are the pieces?" it shouldn't also try to answer "in what order?"
• Left-to-right or top-to-bottom flow. Data enters on one side, results leave the other. Never make the reader hunt for the start.
• Consistent shapes. Whatever shape you pick for databases, use it for all databases. Invented-on-the-fly shapes read as noise.
• A legend when in doubt. Three lines explaining your shapes and arrows cost nothing and remove all doubt.
• Title the diagram. "Delivery confirmation — data flow" beats "Diagram 2."

Best Practices

• Design for deletion. If a component could be thrown away and rebuilt in a week, you're free to get it wrong. Prefer small, replaceable pieces.
• Let requirements buy complexity. Every extra component should point at a requirement. "It might be useful" is not a requirement.
• Integrate, don't replace. The customer's existing systems are usually staying. Your job is to connect to them, not to retire them.
• Document decisions, not just diagrams. A diagram shows what; a one-line note per decision records why — which is what future-you needs.
• Keep diagrams updated with the code. A diagram that disagrees with the system is worse than no diagram — it's confidently wrong.