W-13: Architecture Practice Ways of Work¶

Field	Value
Document	W-13
Title	Architecture Practice Ways of Work
Status	Draft
Owner	CDO
Created	2026-04-05
Review	Quarterly
Depends On	W-01 (Company Operating Rhythm), STD-GOV-124 (ARB Charter & Standards Exception Process), STD-GOV-133 (ADR Lifecycle), STD-GOV-138 (Quality Standards), Architecture Practice Charter

Purpose¶

Define how Simpaisa's Architecture Practice operates: how standards are proposed and maintained, how architectural decisions are recorded, how the ARB functions, and how architectural artefacts are published and governed. This is the single source of truth for architecture process.

If you want to propose a new standard, record an architectural decision, request an exception, or publish to Confluence — this document tells you how.

1. How to Propose a New Standard¶

Any Simpaisa employee may propose a new standard. The typical proposer is an engineering team lead, the CISO, the Data Lead, or the CDO.

Process¶

1. Draft          Write the standard in markdown
2. PR             Create a Bitbucket PR against the Architecture repo
3. Review         Reviewers assigned (minimum: CDO + one subject-matter expert)
4. ARB            Present at next scheduled ARB (or ad-hoc if urgent)
5. Decision       ARB approves, requests changes, or rejects
6. Merge          Approved standard merged to main branch
7. Publish        Automated pipeline publishes to Confluence
8. Index          Maerifa indexes the new content within 24 hours

Step-by-Step¶

Step 1: Draft the standard. - Use the standard metadata table format (see any existing STD-* document for the template). - Write in UK English. - Place the file in the appropriate directory under Standards/ with the correct prefix (e.g., STD-GOV-, STD-SECURITY-, STD-DATA-). - Include: Purpose, Scope, Requirements (with MUST/SHOULD/MAY per RFC 2119), Compliance, and Review sections.

Step 2: Create a Bitbucket PR. - Branch from main. Branch name: std/<short-name> (e.g., std/encryption-at-rest). - PR title: [Standard] <STD-ID>: <Title>. - PR description: One paragraph explaining why this standard is needed and what it governs. - Assign reviewers: CDO (mandatory) + at least one subject-matter expert.

Step 3: Review. - Reviewers provide feedback via PR comments. - Author addresses all comments and re-requests review. - PR must have at least 2 approvals before proceeding to ARB.

Step 4: Present at ARB. - Add the standard to the ARB agenda (see section 3 below). - Presenter: the standard's author or nominated subject-matter expert. - Preparation: circulate the PR link to all ARB members at least 48 hours before the meeting. - Presentation format: 5-minute summary of purpose, scope, and key requirements. No slides — walk through the markdown.

Step 5: ARB decision. - Approved: Proceed to merge. - Approved with conditions: Address conditions, get CDO sign-off, then merge. - Deferred: Rework required. Return to next ARB with revisions. - Rejected: PR closed with documented rationale.

Step 6: Merge. - Author merges the PR after ARB approval. - Merge commit message: feat: add <STD-ID> <Title>.

Step 7–8: Publish and index. - The Confluence publishing pipeline (Git → merge → publish) runs automatically on merge to main. - Maerifa re-indexes on a scheduled basis. Verify the new standard appears in Maerifa within 24 hours of merge. If not, raise an issue.

2. How to Propose an ADR¶

Architecture Decision Records (ADRs) capture significant architectural decisions. ADRs follow the lifecycle defined in STD-GOV-133.

When to Write an ADR¶

Write an ADR when: - Introducing a new technology, framework, or language. - Choosing between two or more viable architectural approaches. - Making a decision that constrains future options (e.g., database choice, messaging platform). - Reversing or superseding a previous ADR. - Any decision that a future engineer would ask "why did we do it this way?"

ADR Template¶

# ADR-<NNN>: <Title>

| Field | Value |
|---|---|
| **ADR** | ADR-<NNN> |
| **Status** | Proposed → Accepted / Rejected / Superseded |
| **Date** | YYYY-MM-DD |
| **Deciders** | Names of decision-makers |
| **Depends On** | Related ADRs or standards |

## Context

What is the situation? What problem are we solving?

## Decision

What did we decide? State it clearly in one or two sentences.

## Rationale

Why this option over alternatives? List alternatives considered and why they were rejected.

## Consequences

What are the positive and negative consequences of this decision?

## Compliance

How will adherence to this decision be verified?

ADR Process¶

Draft: Write the ADR using the template above. Place it in Decisions/ directory.
PR: Create a Bitbucket PR. Branch: adr/<short-name>. Status: Proposed.
Review: CDO reviews all ADRs. Additional reviewers based on scope.
ARB: Present at ARB for decision (same preparation rules as standards).
Decision: ARB sets status to Accepted or Rejected. Author updates the ADR.
Merge and publish: Same as standards.

ADR lifecycle (per STD-GOV-133):

Proposed → Accepted → [Deprecated → Superseded by ADR-XXX]
                    → [Rejected]

ADRs are never deleted. Superseded ADRs link to their replacement. This maintains the full decision history.

3. ARB Meeting Participation¶

The Architecture Review Board meets per W-01: monthly on the first Tuesday (60 min), with ad-hoc sessions as needed (30 min).

Standing Members¶

Role	Name	Attendance
Chair	CDO	Mandatory
Platform Lead	TBD (nominated by CTO)	Mandatory
Security Lead	Hamza Bari (InfoSec Manager)	Mandatory
Data Lead	TBD	Mandatory
Rotating Engineer	One engineer per session (rotated across teams)	Mandatory

How to Get on the Agenda¶

Submit your item (ADR, standard, exception request, architecture review) to the CDO at least 5 business days before the scheduled ARB.
Include: item type, title, one-paragraph summary, PR link (if applicable), and estimated discussion time.
CDO confirms inclusion and circulates the agenda 48 hours before the meeting.

Meeting Format¶

Segment	Duration	Purpose
Previous actions review	10 min	Status of actions from last ARB
ADR reviews	20 min	New ADRs for decision
Standards reviews	15 min	New or revised standards for approval
Exception requests	10 min	Per STD-GOV-124 exception process
Architectural health / AOB	5 min	Emerging concerns, ad-hoc items

Presentation Rules¶

No slides. Walk through the markdown document on screen.
Presenter has 5 minutes to summarise. Remaining time is discussion.
All attendees must have read the pre-circulated material. Meeting time is for decisions, not comprehension.
Decisions recorded as: Approved, Approved with Conditions, Deferred, or Rejected.
Decision rationale documented in the ARB meeting minutes (stored in Governance/ARB-Minutes/).

Ad-Hoc ARB¶

An ad-hoc ARB can be convened by the CDO when an urgent architectural decision cannot wait for the next scheduled session. Minimum attendees: CDO + 2 standing members. 48-hour notice where possible; same-day for genuine emergencies.

4. Standards Exception Process¶

Per STD-GOV-124, any team may request an exception to a published standard.

When to Request an Exception¶

A standard requirement cannot be met due to technical constraints, regulatory requirements, or time pressure.
An alternative approach achieves the same outcome but does not comply with the letter of the standard.
A third-party integration imposes constraints that conflict with a standard.

Exception Process¶

1. Request     Team lead submits exception request (template below)
2. Review      CDO reviews within 3 business days
3. Decision    CDO approves/rejects (minor) or escalates to ARB (major)
4. Conditions  If approved, conditions and expiry date set
5. Track       Exception logged in exceptions register
6. Review      All active exceptions reviewed quarterly at ARB

Exception Request Template¶

Standard: Which standard is the exception for?
Requirement: Which specific requirement cannot be met?
Reason: Why can it not be met?
Alternative: What will be done instead?
Risk: What risk does the exception introduce?
Mitigation: How will the risk be mitigated?
Duration: How long is the exception needed? (Maximum 6 months; must be renewed.)
Requestor: Name and team.

Approval Authority¶

Exception Scope	Approver
Single service, low risk	CDO
Multiple services or moderate risk	CDO + relevant lead (Security, Data, Platform)
Organisation-wide or high risk	ARB

5. Confluence Publishing Workflow¶

All architecture artefacts (standards, ADRs, ways of work, playbooks) are authored in markdown in the Git repository and published to Confluence automatically.

Pipeline¶

Author writes markdown in Git repo
        │
        ▼
Bitbucket PR created → Reviewers approve → Merge to main
        │
        ▼
CI pipeline triggers on merge to main
        │
        ▼
Publishing script converts markdown → Confluence page
        │
        ▼
Page published under Architecture space in Confluence

Rules¶

Git is the source of truth. Never edit directly in Confluence. Confluence is a read-only publishing target.
Each markdown file maps to one Confluence page. Directory structure maps to Confluence page hierarchy.
The publishing pipeline runs on every merge to main that touches files under Standards/, Decisions/, Governance/, or Playbooks/.
If publishing fails, the pipeline alerts the CDO. Failure does not block the merge — the content is already in Git.
Confluence pages include a footer: "This page is auto-published from Git. Do not edit directly. Source: [link to Bitbucket file]."

6. Maerifa Maintenance¶

Maerifa indexes all architecture artefacts for search and discovery.

How Maerifa Indexes New Content¶

Maerifa runs a scheduled re-index daily.
New or updated content merged to main is indexed within 24 hours.
Maerifa indexes: document title, metadata fields, full text, cross-references, and tags.

Verification¶

After merging a new artefact: 1. Wait 24 hours. 2. Search for the document by title and by STD/ADR/W- ID in Maerifa. 3. Verify the content is current (matches the merged version). 4. If the document does not appear, check the Maerifa indexing log and raise an issue.

Maintenance Tasks¶

Task	Frequency	Owner
Verify indexing of new content	After each merge (within 24 hours)	Author of merged content
Review orphaned pages (in Confluence but not in Git)	Quarterly	CDO
Review broken cross-references	Quarterly	CDO or delegate
Maerifa re-index (full rebuild)	Quarterly or on demand	DevOps

7. Technology Radar Update Process¶

The Technology Radar tracks Simpaisa's technology landscape: what we use, what we are evaluating, what we are adopting, and what we are retiring.

Update Cadence¶

Quarterly update at ARB (per W-01 annual calendar, major update in August).
Any ARB member may propose a radar change at any scheduled ARB.

Radar Rings¶

Ring	Meaning
Adopt	Proven at Simpaisa. Default choice for new work.
Trial	Being used in a non-critical context. Results being evaluated.
Assess	Being investigated. No production use yet.
Hold	Do not use for new work. Existing usage to be migrated.

How to Propose a Radar Change¶

Write a brief proposal (1 page max): technology name, current ring, proposed ring, rationale, evidence.
Submit to CDO for ARB agenda (same process as section 3).
ARB discusses and decides.
CDO updates the Technology Radar document and publishes via the standard Confluence pipeline.

Rules¶

Moving a technology to Adopt requires at least 3 months in Trial with documented results.
Moving a technology to Hold requires a migration plan for existing usage.
Technologies not on the radar may not be introduced without an ADR and ARB approval.

8. Architecture Review Triggers¶

Beyond scheduled ARB meetings, certain changes require an ad-hoc architecture review. The responsible team lead must request a review from the CDO before proceeding.

Trigger	Why	Review Format
New microservice or service boundary change	Affects system topology, deployment, and operational complexity	ADR + ARB review
New database (any type)	Data architecture impact, operational burden, licensing	ADR + ARB review
New third-party service or SaaS dependency	Vendor risk, data residency, cost, lock-in	ADR + ARB review
Major refactoring (>500 lines changed across >3 services)	Risk of regression, architectural drift	Architecture review at ARB or ad-hoc
New programming language or framework	Skill requirements, maintenance burden	ADR + ARB review
New cloud service (not previously used at Simpaisa)	Operational knowledge, cost, security posture	ADR + ARB review
Cross-border data flow change	Regulatory implications per market	ADR + Data Lead + ARB review
New payment corridor or settlement mechanism	End-to-end architecture impact, regulatory, security	Full architecture review + ADR
Change to event/message bus topology	Affects all downstream consumers	ADR + ARB review
Deprecation of existing service or technology	Migration planning, consumer impact	ADR + ARB review

Rule: If in doubt, request a review. A 30-minute ad-hoc ARB is far cheaper than unwinding a poor architectural decision after it reaches production.

9. Diagram Standards¶

All architecture diagrams in the repository follow these conventions.

Diagram Types and Tools¶

Diagram Type	Tool / Format	When to Use
System context (C4 Level 1)	ASCII art or Mermaid in markdown	Every new system or major system change
Container diagram (C4 Level 2)	ASCII art or Mermaid in markdown	Every new service, database, or message queue
Component diagram (C4 Level 3)	Mermaid in markdown	When internal structure of a service matters for the decision
Sequence diagram	Mermaid in markdown	API flows, payment flows, authentication flows
Simple flow or topology	ASCII art in markdown	Quick illustrations in ADRs and standards
Deployment diagram	Mermaid or ASCII art	Infrastructure architecture, DR topology

Rules¶

All diagrams must be in text format (ASCII art or Mermaid) so they live in Git, are diffable, and render in Confluence.
No binary image files (PNG, JPG) in the repository unless they are screenshots of external systems for reference.
Mermaid diagrams use the ```mermaid code fence.
ASCII art diagrams use the ``` code fence.
Every diagram must have a title and a brief caption explaining what it shows.
C4 diagrams follow the standard C4 model notation: System (box), Container (box with technology label), Component (box with stereotype), Person (stick figure or labelled box).

Mermaid Example (Sequence Diagram)¶

sequenceDiagram
    participant Merchant
    participant API Gateway
    participant Pay-In Service
    participant Partner Bank

    Merchant->>API Gateway: POST /payments
    API Gateway->>Pay-In Service: Forward request
    Pay-In Service->>Partner Bank: Initiate payment
    Partner Bank-->>Pay-In Service: Payment reference
    Pay-In Service-->>API Gateway: 202 Accepted
    API Gateway-->>Merchant: 202 Accepted

10. Quality Checklist for Artefacts¶

Per STD-GOV-138, all architecture artefacts must meet these quality standards before merging.

Checklist¶

Before submitting a PR for any architecture artefact (standard, ADR, way of work, playbook), verify:

#	Check	Required For
1	Metadata table is complete (Document ID, Title, Status, Owner, Created, Review, Depends On)	All artefacts
2	Purpose section clearly states why this document exists	All artefacts
3	UK English spelling throughout (organisation, colour, authorisation, behaviour, etc.)	All artefacts
4	Cross-references use correct document IDs (e.g., STD-GOV-124, ADR-001, W-01)	All artefacts
5	Requirements use RFC 2119 language (MUST, SHOULD, MAY) consistently	Standards
6	All tables render correctly in markdown preview	All artefacts
7	Diagrams are text-based (ASCII or Mermaid), not binary images	All artefacts
8	No confidential data (credentials, keys, internal IPs) in the document	All artefacts
9	Review cadence specified	Standards, Ways of Work
10	Compliance section explains how adherence is verified	Standards
11	ADR lists alternatives considered with rationale for rejection	ADRs
12	File name follows naming convention (`STD-<DOMAIN>-<NNN>`, `ADR-<NNN>`, `W-<NN>-<NAME>`)	All artefacts

Reviewer Responsibility¶

PR reviewers must verify the checklist above. A PR that fails any mandatory check should not be approved. The CDO has final approval authority on all architecture artefacts.

Compliance with This Document¶

All contributors to the Architecture repository must follow these processes. This document is reviewed quarterly by the CDO at the ARB.

Changes to this document follow its own process: propose via markdown PR, review at ARB, merge on approval.