Hi everyone, Igor Fraga here. This is the third article of these series to unveil the challenges and the role of what we do as a Software Architect. As a software architect, a big part of the job is translation. Not between human languages, but between roles: product managers speak in outcomes, developers in constraints, designers in flows, security in risk, and executives in priorities. When these “languages” don’t align, projects slow down—or fail.

Here’s a true-to-life story from a health-tech launch that shows how ambiguity around a single word—security—nearly derailed the timeline, and how we turned it around with simple tools and habits.

The Setup: One Word, Many Meanings

We were building a new feature for a health-tech platform: secure patient messaging between clinics and patients. Everyone agreed security was “critical.” But “security” meant different things to each group:

• Product meant “users trust us; no scary headlines.”

• Security team meant “no PHI leaks, strong controls, audits.”

• Developers meant “auth is solid, data is encrypted, requests are safe.”

• Legal meant “compliance with privacy laws and auditability.”

• Design meant “simple, safe, not scary to use.”

• Operations meant “we can detect incidents and respond fast.”

All reasonable. But because we didn’t define the word together, each team moved in a slightly different direction. That “slight” drift compounds fast.

The Misalignment Emerges

Two weeks before launch:

• Product expected end-to-end encryption (E2EE) in the messaging feature.

• Engineering implemented encryption in transit and at rest, with role-based access control—strong, but not E2EE.

• Security assumed message redaction in logs and minimal retention; Ops had verbose logs with message snippets to debug issues quickly.

• Design shipped a friendly “secure” badge with no explanation; Legal needed explicit consent text and retention policy visible to users.

Same goal, multiple interpretations. Our risk: delay the launch or ship something we’d need to rework under pressure.

The Reset: Define the Word Together

We paused. In a one-hour workshop, we agreed on the meaning of “security” for this feature, written in plain language with testable criteria.

Security definition for patient messaging (v1):

• Data protection:

  • TLS 1.2+ in transit; AES-256 at rest.

  • No message bodies in logs; IDs and metadata only.

• Access control:

  • Only sender, recipient, and authorized clinicians can read messages.

  • Support can access metadata for troubleshooting; message content access requires explicit, auditable approval.

• Privacy and retention:

  • Retain message bodies for 180 days (legal requirement X), then delete or anonymize.

  • Users can request deletion; we honor within Y days.

• Auditability:

  • Every read/write is logged with user/service ID, timestamp, purpose.

  • Alerting on anomalous access patterns.

• UX:

  • Clear security copy: what “secure” means, how data is used, and retention.

  • Consent flow before first message; link to policy.

• Out of scope (v1):

  • End-to-end encryption.

  • Message export by patients.

With this aligned definition, we could make decisions without guessing.

Tools and Habits That Keep Teams Aligned

We didn’t rely on “being careful.” We changed how we communicate.

1. Vocabulary Glossary

• We created a living glossary for high-risk words: security, retention, consent, audit, incident, E2EE.

• Each term had a one-line definition and acceptance test (how we verify it’s done).

• We pinned this in our docs and Slack channel.

2. Architecture Decision Records (ADRs)

• We wrote short ADRs for key choices:

  • “No E2EE in v1; enforce encryption in transit/at rest, with audited content access. Rationale: supportability, time-to-launch, legal needs. Revisit in v2.”

  • “Logs exclude message bodies. Rationale: minimize PHI exposure; add correlation IDs instead.”

• ADRs made decisions visible and durable, so we didn’t re-argue them weekly.

3. Two Diagrams, Max

• Context diagram: who can access what data paths (patient, clinician, support; services; storage).

• Sequence diagram: “send message” and “read message,” with security controls marked at each step (authentication, authorization, encryption, logging).

• We annotated diagrams with the glossary terms, e.g., “no bodies in logs.”

4. Regular Check-ins with Purpose

• Weekly cross-functional “quality attributes” check-in (security, privacy, performance, reliability).

• Agenda format:

  • What changed?

  • Risks detected?

  • Decisions needed?

  • Actions and owners.

• 30 minutes, timeboxed. The goal: detect drift early.

5. User-Facing Copy as an Artifact

• We reviewed the exact text users would see: what “secure” means, what we store, how long we keep it, and how consent works.

• This made legal, product, and design align on the same facts and tone.

6. Logging and Access Drills

• We ran small drills:

  • Verify logs don’t contain message bodies.

  • Try to access content as a support user—ensure it’s blocked or requires explicit approval.

  • Review audit logs to confirm “who read what, when, and why” is traceable.

• Drills convert policy into confidence.

The Turnaround: From Confusion to Clarity

Once we aligned:

• Engineering added a redaction layer to the logger and updated access policies.

• Design adjusted the badge to link to a “How your data is protected” page.

• Legal approved the consent flow and retention copy.

• Security set alerts for unusual access and added a data retention job with reports.

• Product updated the timeline with a small buffer to complete the drills.

We shipped on time—with fewer post-launch surprises—because we shared the same map.

Practical Templates You Can Reuse

Use these verbatim or adapt to your context.

Security Definition Template (per feature)

• Data protection: [in transit], [at rest], [redaction].

• Access control: [who can read], [who can’t], [approval path].

• Privacy/retention: [duration], [user rights], [deletion SLA].

• Auditability: [events logged], [alert thresholds], [review cadence].

• UX: [copy], [consent], [policy links].

• Out of scope (this release): [items].

Architecture Decision Record (ADR)

• Title:

• Context:

• Decision:

• Rationale:

• Alternatives considered:

• Consequences (positive/negative):

• Review date:

Meeting Cadence

• Weekly quality-attributes sync (30 min).

• Agenda: changes, risks, decisions, actions.

• Owner: architect or tech lead; recorder rotates.

Two-Diagram Rule

• Context diagram with data boundaries and actors.

• Sequence diagram for 1–2 critical flows with controls marked.

• Keep both updated; remove obsolete diagrams.

Glossary Entry

• Term: Security (Messaging v1)

• Definition: [one sentence]

• Acceptance test: [how we verify it’s true]

• Owner: [role]

• Next review: [date]

Communication Patterns That Scale

• Say the quiet parts out loud: If a term has multiple meanings, pause and define it.

• Prefer artifacts over memory: If it matters, write it down where everyone can see it.

• Make decisions easy to find: ADRs prevent decision amnesia.

• Show, don’t only tell: Diagrams reveal gaps words hide.

• Close loops fast: Short, regular check-ins remove surprises.

Final Thought

Architecture is a team sport. My job is to help the team speak a shared language so we solve the same problem in the same way. Words like “security,” “performance,” or “MVP” are not self-explanatory. When we define them together, document decisions, and keep a steady rhythm of check-ins, we trade confusion for momentum—and ship with confidence.

In the next article, we will dive deep into a more technical subject that is key to the success of a project, “Choosing Technologies: The Beauty and the Beast Trap”. Selecting the right tool for the job matters. Do you chase the new, shiny technology, or stick to the tried and tested? See you in the next post!