Pro: an architecture team built around your company
The free kit gives any team five architects who design and review every change the same way. Pro is for companies going AI native: every team designs and records its decisions with agents, on your standards.
Architects tuned to your domain, stack, regulators and house standards.
One practice across every team and repository.
Help getting there: profiles set up, decision makers coached, first designs reviewed with you.
A design mistake caught before the code is the cheapest one you will fix. A written decision outlives the person who made it. We are building Pro now. The kit stays free.
Two requirements documents from a made-up Saudi wallet, followed through the whole team. Each step shows what you type, which architect picks it up, what it reads, what it writes, and where you decide.
Enterprise
Solution
Cloud and infra
Security
Research
The board
You decide
BRSD-014 · simulated run
Instant transfers to any Saudi bank
Samra Pay, a made-up Saudi wallet, wants customers to send money to any Saudi bank account in seconds. It reads like one feature, but it buys a fraud service, pays the bank per transfer and signs payment messages. So it goes through research and a demand assessment before anyone designs.
10 steps
8 commands
2 decisions for you
7 new documents
BRSD-014docs/brsd/BRSD-014-instant-transfers.pdf
Business requirements
BR-1A customer sends money from the wallet to any Saudi IBAN, at any hour, settled in seconds through the sponsor bank's instant payments link.
BR-2The recipient's name is shown before the customer confirms.
BR-3Every transfer is screened for fraud and sanctions in under 300 ms.
BR-4Customers can share a request-to-pay link with an amount.
BR-5Daily limit of SAR 20,000 per customer.
BR-6Compliance asks for transfer records to be kept for 10 years.
Non-functional
NFR-199.95% availability for sending.
NFR-2All customer data stays in the Kingdom.
docs/architecture/project.yaml
project:
name: Samra Pay
summary: Consumer wallet, licensed as a payments company
stage: live, about 400,000 customers
decision_maker: CTO; the MLRO for AML policy
stack:
backend: Node 20, TypeScript, NestJS
database: PostgreSQL 16 on Cloud SQL, HA
auth: OIDC, device binding, step-up OTP
hosting:
primary_cloud: GCP
region: me-central2 (Dammam)
residency_note: customer data stays in the Kingdom
integrations:
- name: Sponsor bank
purpose: IBAN accounts, instant payments
regulation:
- SAMA rules for payment service providers
- SAMA AML and CTF rules
- Anti-Money Laundering Law
- SAMA Cyber Security Framework
- PDPL
data_protection:
most_sensitive: national ID and Iqama numbers,
IBANs, balances, screening results
abuse_cases:
- customer reads another customer's data
- staff open a record not assigned to them
- customer learns they were flagged
log_rules: no ID numbers, IBANs or tokens
The company profile. It is the same for every BRSD; this one doesn't change it.
The route it took
A BRSD enters as a business requirement. It has a source to read and it buys things, so research and a demand assessment come before design. You decide twice.
Stacked boxes run in parallelDashed boxes are your decisionsEach box jumps to its step
01
Research
Read the BRSD before anyone designs
There is a source nobody has read in full, so research goes first. It checks the question bank for anything already answered, then separates what the BRSD proves from what it only claims.
Q-001 Does the bank contract include fraud screening, or only sanctions?
Enterprise
Q-002 Which payment message keys do we hold, and must they sit in an HSM?
Security
Q-003 Can the bank call us back, and does it need private connectivity?
Cloud and infra
Q-004 Is a transfer its own bounded context, or part of Wallet?
Solution
Q-005 What can someone do with a forged request-to-pay link?
Security
Q-006 What retention actually applies to transfer records?
Enterprise
02
Enterprise
Should we do it, and buy or build the fraud screening?
BR-3 needs a fraud service, the bank charges per transfer, and a bank integration is hard to undo. Any one of those calls for a demand assessment. You want the options first, so the enterprise architect writes an outline.
>/arch-enterprise Outline for BRSD-014: build, buy, or use the bank's fraud screening? Brief: practice/research/2026-10-27-brsd-014.md
→ enterprise-architect, answering Q-001 and Q-006 on the way
Reads
the research brief
practice/ea-playbook.md §2
practice/templates/outline.md
visions/roadmaps/
Writes
New: outlines/solutions/instant-transfers.md
Changed: questions.yaml (Q-001, Q-006 answered)
Outline: options scored 1 to 5
Option
Function
Feasibility
Fit
Cost
Note
A. Build a rules engine in house
2
4
5
4
No device or network signals, so weak against account takeover
B. Buy an in-Kingdom fraud scoring service, behind our own interface
5
4
4
2
Recommended. Data stays in Saudi; the interface keeps A open
C. Use the bank's screening only
3
5
3
5
Q-001: the contract covers sanctions only. Keep it for sanctions
You decide
Go. Option B for fraud, with the bank's sanctions screening (C) alongside. Budget for 12 months, revisit at the vendor's renewal. On Q-006 the regulation sets the floor and BR-6's 10 years is a business choice, which you accept.
03
The board
Two questions that cross lanes
Where does the transfer ledger live, and do we call the bank inside the customer's request? Solution, cloud and security each own part of the answer, so the board runs them in parallel and merges what they say.
>/arch-board Should instant transfers get their own service and database, and should we call the bank synchronously in the customer's request?
→ Picks solution, cloud and security. Enterprise sits out: no vendor, cost or roadmap change beyond the approved outline
Reads
the outline
the research brief
src/wallet/ and src/ledger/
Writes
Changed: questions.yaml (Q-004 answered)
Solution
A Transfers module inside the existing API, with its own schema and an outbox table. A worker submits to the bank. One deploy and one database to reason about.
Security
Whatever can sign a payment message is the crown jewel. If the main API is compromised, it must not be able to sign. Wants a separate service.
Cloud and infra
A second full service doubles the private connectivity and the on-call surface. Fine with a tiny service if it holds no business logic.
The board's merged reply
Recommendation Transfers stays a module with an outbox. Bank submission is
async from a worker; the customer sees "Sending", then "Sent".
Signing moves to a small signer service, the only identity
allowed to use the HSM key.
Disagreement Security against solution on a separate service. Settled by
splitting out only the signer.
Decision type Technology and design (EA playbook). Settled in the HLD.
Next The solution architect writes the HLD.
04
Solution
The HLD: the design you say yes or no to
/arch-doc hands the solution architect its solution-design skill and the HLD template. The approved outline and the board's answer go in as context, so the HLD builds on them instead of reopening them.
>/arch-doc feature Instant transfers to any Saudi bank (BRSD-014). Outline: outlines/solutions/instant-transfers.md. Board: module, outbox, separate signer.
→ solution-architect, with the solution-design skill, scope F (feature)
Reads
practice/templates/hld.md (v4)
the outline and the brief
standards/guidelines/
src/wallet/, src/auth/ (cited by file:line)
Writes
New: designs/solutions/instant-transfers/hld.md
Changed: questions.yaml (Q-007 for security, Q-008 for cloud)
hld.md §4.1 Pillars
1. Money is integer halalas, never a float.
2. Every transfer has one idempotency key.
3. A transfer is a state machine; the bank
is the source of truth for "settled".
4. Nothing signs except the signer.
hld.md §7 Data governance
Data
Class
Kept
Leaves KSA
Transfer record
Confidential
10 years
No
Recipient IBAN and name
Personal
10 years
No
Device signals sent to the fraud vendor
Personal
90 days, at the vendor
No
hld.md §8.2 Who can do what
Role
Create a transfer
Read a transfer
Customer
From their own wallet only
Their own only
Support agent
No
Masked IBAN only
Signer service
Sign only
No
The HLD ends with a question for each of the next two architects: threat-model the flows and the request-to-pay link, and plan the bank link, the HSM, the worker and the cost. Those two run at the same time.
05
Security
Threat model, in parallel with the change plan
The security architect models the HLD's flows, not the BRSD's wishes. It answers Q-002, Q-005 and Q-007, and names the abuse-case tests the build must contain.
>/arch-security Threat model the flows in designs/solutions/instant-transfers/hld.md, including request-to-pay links.
Change plan: what changes in the cloud, and what it costs
The design adds a worker, a signer, a private link to the bank and an HSM key. The cloud and infra architect writes the steps, the cost and the rollback, and answers Q-003 and Q-008.
>/arch-cloud-infra Change plan for designs/solutions/instant-transfers/hld.md: private link to the sponsor bank, HSM signing, transfers worker, cost.
1. Reserve a static egress IP (Cloud NAT)
for the bank to allowlist.
2. HA VPN to the bank, which requires
IPsec. Q-003: it calls back over it.
3. KMS key ring at HSM protection level in
me-central2. Signer identity only.
4. Deploy transfers-worker and signer on
Cloud Run, minimum one instance each.
5. Migrate the transfers schema.
6. Scheduler: reconcile every 5 minutes.
Monthly cost, illustrative
Item
SAR
HA VPN, 2 tunnels
270
Cloud NAT and static IP
150
Two always-on Cloud Run services
400
HSM key and operations
50
Total, before bank and vendor fees
870
Rollback: turn the feature flag off and let the worker drain the outbox. The VPN and the key stay, since they carry no customer traffic on their own.
07
Solution
The LLD (the SAD) and the ADRs
With the threat model and the change plan in, the same command writes the software architecture document on arc42. Each lasting decision becomes an ADR written by the architect whose lane it is in, so the fraud vendor is enterprise's and the HSM signer is security's. Then you take the design decision.
>/arch-doc feature instant-transfers: write the LLD from the HLD, threat-model.md and change-plan.md
→ solution-architect, with the solution-design skill
Reads
practice/templates/lld.md (v3, arc42)
hld.md, threat-model.md, change-plan.md
Writes
New: designs/solutions/instant-transfers/lld.md
New: decisions/0001 to 0004
Changed: decisions/README.md
Changed: landscapes/app/ (logical view)
ADRs, as Proposed
ADR
Decision
Lane
0001
Submit to the bank through an outbox and a worker
Solution
0002
Buy fraud scoring from an in-Kingdom vendor
Enterprise
0003
Store money as integer halalas
Solution
0004
Sign payment messages only in a separate signer with an HSM key
Security
lld.md §16 Rollout
Phase 1 staff wallets only, 1 week
Phase 2 5% of customers, SAR 5,000 a day
Phase 3 everyone, SAR 5,000 a day
Phase 4 SAR 20,000 a day (BR-5)
Exit, each phase: no reconcile mismatches,
fraud losses under the agreed threshold
You decide
Approve, with a condition. Launch at SAR 5,000 a day for 30 days before raising it to BR-5's SAR 20,000. The four ADRs move from Proposed to Accepted.
08
Solution
A question comes up while building
You build with your coding assistant from lld.md. In staging, the bank's settlement callback sometimes arrives before the worker has committed. Ask the solution architect in its own context, so your coding chat stays clean.
>/arch-solution The bank's settlement callback sometimes arrives before our worker commits the submission. How should the state machine handle it?
Never answer the bank with a 404. Store the callback in bank_events, keyed by
the bank's reference, and return 200. After the worker commits, it looks for an
early event and applies it. The 5 minute reconcile job picks up anything left.
This fits ADR-0001, so there is no new ADR. Added the runtime scenario
"callback before commit" to lld.md §6.3, and the test
early_settlement_callback_is_applied_after_commit.
09
Solution
Check the branch against the standards before the PR
/arch-conform reads every guideline, the accepted ADRs and the threat model's required tests, and checks the branch against them. With fix, it repairs what it finds and keeps each guideline's Appendix A true.
>/arch-conform feature/instant-transfers fix
→ solution-architect, as a conformance check against main
Reads
standards/guidelines/
decisions/0001 to 0004
threat-model.md
the diff against main
Writes
Changed: src/ and test/ (5 fixes)
Changed: standards/guidelines/*.md Appendix A
Breaches found and fixed
Severity
Where
Rule
Result
High
src/transfers/transfer.service.ts:88
Observability R7: logs the full recipient IBAN
Fixed: logs transfer_id
High
src/transfers/transfer.entity.ts:14
ADR-0003: amount typed as a float
Fixed: bigint halalas
High
test/transfers/
Threat model: a required abuse test is missing
Fixed: test added
Med
src/transfers/transfers.controller.ts:41
API layering R2: limit check in the controller
Fixed: moved to the service
Low
src/bank/callback.controller.ts:23
Observability R4: a 4xx logged as an error
Fixed: logged as info
It also proposes two checks so nobody has to remember these: a lint rule that rejects number on any field named amount, and a CI step that fails when a threat model's required test is missing.
10
Solution
Ship, and make the documents true again
The PR is reviewed against the design and export.py --check passes. After the merge, one command marks the design Built and updates every view that changed.
Template gap reported: the HLD template has no prompt for money and rounding. It suggests adding one to practice/templates/hld.md as v5, with a changelog line.
Command coverage
All eight architect commands, each used when its trigger appeared. None of them committed anything.
Command
Step
Triggered by
Left behind
/arch-research
1
A document nobody had read in full
A brief and 6 owned questions
/arch-enterprise
2
A purchase, a per-transfer fee, a bank link hard to undo
An outline with 3 scored options
/arch-board
3
A question three lanes each owned part of
One recommendation, the disagreement settled
/arch-doc
4, 7
An approved demand that needs a design
The HLD, then the LLD (SAD), with 4 ADRs from three lanes
/arch-security
5
The HLD's question for security
A threat model and 3 required tests
/arch-cloud-infra
6
New infrastructure in the HLD
A change plan with cost and rollback
/arch-solution
8, 10
A question during the build; then the merge
An answer and an LLD update; status Built
/arch-conform
9
A branch about to become a PR
5 breaches fixed, 2 checks proposed
BRSD-021 · simulated run
Remote onboarding with eKYC
Months later, the same wallet wants customers to open an account in minutes without visiting a branch. KYC is a legal duty, so the route is heavier: more regulation to read, a vendor to buy, rules that compliance owns, and data the law treats as the most sensitive the company holds.
10 steps
8 commands
2 decisions for you
8 new documents
BRSD-021docs/brsd/BRSD-021-ekyc-onboarding.pdf
Business requirements
BR-1A new customer opens a wallet in under 3 minutes, fully remote, by verifying with Nafath.
BR-2Name, date of birth, nationality and ID expiry come from government records, never typed.
BR-3Every customer is screened against sanctions and PEP lists at onboarding, and again every day.
BR-4Each customer gets a risk rating. A high-risk customer waits for compliance review before the wallet works.
BR-5Two tiers: Tier 1 after Nafath, with low limits; Tier 2 after occupation and source of funds.
BR-6Re-verify when a national ID or Iqama expires.
BR-7Existing customers, onboarded the old way, are brought up to the new standard.
Non-functional
NFR-1Fewer than 25% of people who start onboarding drop out.
NFR-2All identity data stays in the Kingdom.
docs/architecture/project.yaml
project:
name: Samra Pay
summary: Consumer wallet, licensed as a payments company
stage: live, about 400,000 customers
decision_maker: CTO; the MLRO for AML policy
stack:
backend: Node 20, TypeScript, NestJS
database: PostgreSQL 16 on Cloud SQL, HA
auth: OIDC, device binding, step-up OTP
hosting:
primary_cloud: GCP
region: me-central2 (Dammam)
residency_note: customer data stays in the Kingdom
integrations:
- name: Sponsor bank
purpose: IBAN accounts, instant payments
regulation:
- SAMA rules for payment service providers
- SAMA AML and CTF rules
- Anti-Money Laundering Law
- SAMA Cyber Security Framework
- PDPL
data_protection:
most_sensitive: national ID and Iqama numbers,
IBANs, balances, screening results
abuse_cases:
- customer reads another customer's data
- staff open a record not assigned to them
- customer learns they were flagged
log_rules: no ID numbers, IBANs or tokens
The same profile as the transfers example. AML law, ID numbers and tipping off were already in it, because they are true of the company, not of this BRSD. Nafath and Yakeen join integrations once the build ships.
The route it took
The same entry, with one difference: the board meets on a business question, who owns the risk rules. So the enterprise architect sits on it and the cloud architect sits out.
Stacked boxes run in parallelDashed boxes are your decisionsEach box jumps to its step
01
Research
Read the regulation and the provider guides first
KYC design rests on what the rules require and what Nafath and Yakeen actually return. Nobody should design from memory, so research reads four sources and separates fact from assumption.
>/arch-research docs/brsd/BRSD-021-ekyc-onboarding.pdf, the SAMA AML and CTF rules, and the Nafath and Yakeen guides in docs/vendors/
→ research-architect. It finds Q-006 on retention already answered for transfers, and asks only what differs for KYC records
Reads
project.yaml
practice/research/questions.yaml
the BRSD and the AML rules
docs/vendors/nafath-guide.pdf
docs/vendors/yakeen-guide.pdf
Writes
New: practice/research/2026-10-27-brsd-021.md
Changed: practice/research/questions.yaml (Q-009 to Q-015)
Due diligence must finish before the relationship starts
Fact, AML rules
Yakeen gives us the customer's address
Claim. The guide lists identity fields only
Nafath covers every customer
Claim. Citizens and residents, not visitors
We need a selfie and liveness check
Claim. Depends on Q-015
Questions, one owner each
Question
Owner
Q-009 Can we contract Yakeen directly, or only through a licensed aggregator?
Enterprise
Q-010 How long are KYC records kept after the relationship ends?
Enterprise
Q-011 Do we need to store an ID image at all?
Security
Q-012 Does Nafath call us back, and from which addresses?
Cloud and infra
Q-013 Is KYC its own context, or part of Identity (login)?
Solution
Q-014 Which sanctions lists are mandatory, and how fresh must they be?
Enterprise
Q-015 With Nafath, is a selfie liveness check still needed?
Security
02
Enterprise
What to build, what to buy, and who to contract with
Per-check fees for Yakeen, a screening vendor, and a regulated process compliance will live with for years. That is a demand assessment, and you want the options first.
>/arch-enterprise Outline for BRSD-021: build, buy or mix for eKYC, screening and monitoring. Brief: practice/research/2026-10-27-brsd-021.md
→ enterprise-architect, answering Q-009, Q-010 and Q-014
Reads
the research brief
practice/ea-playbook.md §2
practice/templates/outline.md
landscapes/inventory.md (vendors already held)
Writes
New: outlines/solutions/ekyc-onboarding.md
Changed: questions.yaml (3 answered)
Outline: options scored 1 to 5
Option
Function
Feasibility
Fit
Cost
Note
A. Build on direct government integrations and raw list feeds
4
2
4
3
Months of approvals, and we maintain list matching ourselves
B. Buy one all-in-one eKYC and AML platform
4
5
2
2
Fast, but the risk rules live in the vendor's product, not ours
C. Nafath and Yakeen through a licensed aggregator; buy screening; build rating and case review
5
4
5
3
Recommended. We own the rules the regulator will ask us to explain
You decide
Go with C. Q-009: the aggregator holds the Yakeen licence and we hold a contract with the aggregator. Q-010: keep KYC records 10 years after the relationship ends. Q-014: UN and local lists are mandatory and refreshed daily, which BR-3 already meets.
03
The board
Who owns the risk-rating rules, and where do they live?
Compliance writes the rules, engineering runs them, and a changed rule can quietly let risky customers through. That crosses business, design and security, so the board convenes.
>/arch-board Who owns the KYC risk-rating rules, where do they live (code, config or a rules engine), and is KYC part of Identity?
→ Picks enterprise, solution and security. Cloud sits out: nothing here changes where it runs
The rules are policy. The MLRO owns them, and every change needs an approval trail the regulator can read. Write it down as a policy.
Solution
No rules-engine product. Rules are versioned config in the repo, changed by pull request. KYC is its own context; Identity keeps login only.
Security
A rule change is a fraud vector. Four-eyes approval, and every rating stores the rule version it was made with, so any past decision can be replayed.
The board's merged reply
Recommendation Rules are versioned config. A change needs a PR approved by an
engineer and the MLRO. Every rating records its inputs, the
rule version and the outcome. KYC is its own bounded context.
Disagreement Enterprise wanted compliance to edit rules in an admin screen.
Solution and security preferred PRs. Settled on PRs now, and a
screen later if compliance edits more than monthly.
Decision type Business (a policy the MLRO owns) and design (an ADR).
Next Enterprise drafts the policy; solution writes the HLD.
04
Solution
The HLD: onboarding as a state machine you can explain
The outline and the board's answer go in as context. The HLD's job is to make every KYC decision traceable, and to keep as little identity data as the law allows.
>/arch-doc feature eKYC onboarding (BRSD-021). Outline: outlines/solutions/ekyc-onboarding.md. Board: rules as versioned config, KYC its own context.
→ solution-architect, with the solution-design skill, scope F (feature)
Reads
practice/templates/hld.md (v4)
the outline, the brief, the draft policy
src/identity/ (cited by file:line)
standards/guidelines/
Writes
New: designs/solutions/ekyc-onboarding/hld.md
Changed: questions.yaml (Q-016 for security, Q-017 for cloud)
hld.md §6 Onboarding states
Started
Nafath verified
Records fetched
Screened
Rated
Active
From Rated, a high-risk customer goes to In review, which ends in Active or Rejected. Any step can resume where it stopped.
hld.md §4.1 Pillars
1. Government records over typed data.
2. Keep the minimum: no ID images for
Nafath-verified customers.
3. Every decision is explainable:
inputs, rule version, outcome.
4. Never tip off. A customer under review
sees the same message as any slow
application.
hld.md §7 Data governance
Data
Class
Kept
National ID or Iqama number
Restricted
10 years after exit
Name, birth date, nationality
Personal
10 years after exit
Nafath transaction reference
Evidence
10 years after exit
Screening hits
Restricted
10 years after exit
Rating, inputs, rule version
Confidential
10 years after exit
hld.md §8.2 Who can do what
Role
Sees
Can do
Customer
Their own status, never the rating
Start, resume, add Tier 2 details
Compliance analyst
Cases assigned to them
Approve or reject a case
MLRO
All cases
Approve rule changes, reassign cases
Support agent
Status and a masked ID
Nothing on KYC
Engineer
No production KYC data
Deploy
05
Security
Threat model: identity fraud, insiders, and tipping off
It runs at the same time as the change plan. The security architect models the HLD's flows and answers Q-011, Q-015 and Q-016.
>/arch-security Threat model designs/solutions/ekyc-onboarding/hld.md, including insiders and the review flow.
Q-011 No ID images for Nafath-verified
customers. Storing them adds risk
and proves nothing the records
don't already prove.
Q-015 No selfie liveness for Tier 1 when
Nafath succeeds. Revisit if a flow
for visitors without Nafath is
added.
06
Cloud and infra
Change plan: a separate store for identity data
The HLD keeps KYC data apart from the wallet. The cloud and infra architect plans the store, its key, the daily re-screening job and the provider connectivity, and answers Q-012 and Q-017.
>/arch-cloud-infra Change plan for designs/solutions/ekyc-onboarding/hld.md: KYC data store, keys, daily re-screening job, aggregator connectivity, cost.
→ cloud-infra-architect, reusing the static egress IP from instant transfers
1. A new Cloud SQL database for KYC, HA,
me-central2, with its own identity.
2. A customer-managed key in KMS; only
the KYC service may decrypt.
3. Q-012: the aggregator calls us back.
Allowlist its addresses on one route;
reuse the static egress IP outbound.
4. A Cloud Run job re-screens every
customer daily at 02:00 Riyadh time.
5. A log sink filter that drops 10-digit
numbers starting 1 or 2 (ID, Iqama).
Monthly cost, illustrative
Item
SAR
Cloud SQL HA instance for KYC
1,400
Daily re-screening job
60
KMS keys and operations
20
Static egress IP
0, reused
Total, before per-check fees
1,480
Rollback: send new sign-ups back to the old manual flow with a flag. The KYC database stays, because records already written fall under the retention rule.
07
Solution
The LLD (the SAD) and the ADRs
With the threat model and the change plan in hand, the same command writes the SAD. Each lasting decision becomes an ADR from the architect whose lane it is in: solution, security or enterprise. Then you take the design decision.
>/arch-doc feature ekyc-onboarding: write the LLD from the HLD, threat-model.md and change-plan.md
→ solution-architect, with the solution-design skill
Reads
practice/templates/lld.md (v3, arc42)
hld.md, threat-model.md, change-plan.md
Writes
New: designs/solutions/ekyc-onboarding/lld.md
New: decisions/0005 to 0008
Changed: decisions/README.md
Changed: landscapes/app/ (logical and trust-boundary views)
ADRs, as Proposed
ADR
Decision
Lane
0005
Keep KYC in its own bounded context and database
Solution
0006
Do not store ID images for Nafath-verified customers
Security
0007
Keep risk rules as versioned config approved by the MLRO
Solution
0008
Buy screening; build risk rating and case review
Enterprise
lld.md §16 Rollout
Phase 1 staff only, 1 week
Phase 2 10% of new sign-ups, with the
manual flow as a fallback
Phase 3 all new sign-ups
Phase 4 existing customers re-verify
with Nafath at next login (BR-7)
Exit, each phase: drop-off under 25%,
no unassigned case older than 48 hours
You decide
Approve, with two conditions. The MLRO signs the first rule set and the policy before Phase 2, and Phase 4 finishes within 6 months. The policy moves to Agreed and the ADRs to Accepted.
08
Solution
A shortcut is proposed while building
In staging, the records lookup sometimes times out, and product suggests letting customers type their details instead. Ask the solution architect before anyone does that.
>/arch-solution Yakeen sometimes times out during onboarding. Can we let the customer type their details and continue?
No. Typed details break pillar 1 and BR-2, and a wallet must not activate
before due diligence finishes. Instead:
- Hold the onboarding before "Records fetched" and tell the customer:
"We're finishing your checks. We'll notify you in a few minutes."
- Retry with backoff behind a circuit breaker, 5 seconds per call.
- Log the event kyc.records.fetch_failed at warn, with customer_id only.
This fits ADR-0005, so there is no new ADR. Added the runtime scenario
"records source down" to lld.md §6.2, and the test
onboarding_resumes_after_records_timeout.
09
Solution
Check the branch against the standards before the PR
KYC is where a breach costs the most, so the check runs against every guideline, the accepted ADRs and the threat model's required tests.
>/arch-conform feature/ekyc-onboarding fix
→ solution-architect, as a conformance check against main
Reads
standards/guidelines/
decisions/0005 to 0008
threat-model.md
the diff against main
Writes
Changed: src/ and test/ (5 fixes)
Changed: standards/guidelines/*.md Appendix A
Breaches found and fixed
Severity
Where
Rule
Result
High
src/kyc/kyc.service.ts:57
Observability R7: logs the national ID number
Fixed: logs customer_id
High
src/kyc/review.controller.ts:30
Threat 5: tells the customer "Rejected: sanctions match"
Fixed: same message as review
High
test/kyc/
Threat model: analyst_cannot_open_case_not_assigned is missing
Fixed: test added
Med
src/kyc/risk.ts:112
ADR-0007: thresholds written into the code
Fixed: moved to versioned config
Med
src/kyc/yakeen.client.ts:18
Communication patterns: an outbound call with no timeout
Fixed: 5 s timeout and retry
Two checks proposed: a test that fails when any log line holds a 10-digit number starting with 1 or 2, and a contract test that the In review and Rejected responses are byte for byte the same.
10
Solution
Ship, and make the documents true again
The PR is reviewed against the design and the export check passes. After the merge, the design is marked Built and every view that changed is updated.
>/arch-solution mark ekyc-onboarding Built
→ solution-architect
Reads
the merged code
hld.md, lld.md
landscapes/
Writes
Changed: hld.md, lld.md (status: Built)
Changed: landscapes/app/ integration view (Nafath, Yakeen through the aggregator, screening vendor)
Template gap reported: the HLD template has nowhere to list the decisions a regulator may ask you to explain. It suggests an explainability prompt in practice/templates/hld.md §7, as v5.
Command coverage
All eight architect commands, each used when its trigger appeared. None of them committed anything.
Command
Step
Triggered by
Left behind
/arch-research
1
A BRSD, a regulation and two provider guides
A brief and 7 owned questions
/arch-enterprise
2
Per-check fees, a vendor, a long-lived regulated process
An outline with 3 scored options
/arch-board
3
Rule ownership, across business, design and security
One recommendation and a draft policy
/arch-doc
4, 7
An approved demand that needs a design
The HLD, then the LLD (SAD), with 4 ADRs from three lanes
/arch-security
5
The HLD's flows and identity data
A threat model and 4 required tests
/arch-cloud-infra
6
A new data store, a key and a scheduled job
A change plan with cost and rollback
/arch-solution
8, 10
A shortcut proposed during the build; then the merge
A refusal with a safe alternative; status Built
/arch-conform
9
A branch about to become a PR
5 breaches fixed, 2 checks proposed
Simulated. These are simulations. No agent ran. They are written from the kit's own commands, agents and templates, so the routing, file paths and document sections match what the team produces. Samra Pay, its vendors, the code paths and the costs are invented, and the regulatory details are illustrative. Before building either for real, run /arch-research on the current rules.