SaFi Bank Space : Guidelines for tech docs

Solution Blueprint

High level architecture view on the overall solution. Each domain has its page in Solution Blueprint / Domains which contains

• Overview of domain’s functional & non-functional scope (bullet list)

• High level diagram showing domain’s services and external dependencies

• Short description of the components depicted on the diagram in form of a table

Note: content is authored primarily by the Architecture team however responsibility for providing up-to-date information once changes happen and/or are planned is on the squad’s tech leads.

Domain specific pages

Each domain has its dedicated space in the root named as “Domain: XYZ” which contains

• Deep dive into the domain’s specific topics providing the reader comprehensive introduction into domain’s requirements and their technical implementation

• The domain’s scope described in form of user stories organized into epics

• Technical documentation with explanations of the technical realization of the epics and user stories

• All historical and obsolete content is moved into the Archive folder

Note: content is authored by the squad’s team members and responsibility for keeping the content up-to-date in on squad’s tech leads. 

Guidelines and examples for technical documentation

Architecture

Overview of the domain’s architecture in a form of component diagram. Multiple diagrams are provided in case of a complex domain e.g. Loans are split between Overdraft and Consumer Loans.

Example of component diagram:

Services / components description

Individual pages dedicated to the components delivered within the domain containing comprehensive information how the component / service is implemented. The content depends very much on the character of the particular service (e.g. different content is available for native mobile app, backend service or a smart contract). 

Checklist of possible topics that needs to be addressed here

• Transactional processing

• Idempotency and retry-ability

• Communication patterns used

• Communication protocols used

• Approach to scalability

• Performance & capacity requirements

• Approach to security

• Approach to batch (scheduled) capabilities

• Technical dept introduced

• …

Note: A nice example of documentation of a particular component is the documentation of the Scheduled process in the Customers domain or Debt manager implementation in smart-contract.

API documentation & message structures

Description or link to a documentation for all APIs and messages being produced or consumed by domain’s components. 

Contains functional and non-functional aspects relevant for the integration, i.e. communication protocol, authentication, SLAs, idempotency, versioning, etc. 

Note: example Overdraft technical documentation

Data / domain model

High level ER diagram showing key entities managed by the domain. Description of the entities and their relationships. For key entities there is a state-chart diagram representing the key states and their transitions. 

Process flow

Process flow diagram organized into swimlanes representing individual services (or more granular components if appropriate). The goal is to visualize the process flow of actions relevant for a particular user story or epic. The flow contains both the happy-day scenario and also error scenarios. Textual explanation is nice-to-have (depending on the complexity of the process). 

This should provide a clear description on how a particular user story is implemented.  

May be in a form of an activity diagram:

Or in a form of a sequence diagram: 

Releases

It should be clear from the documentation what is relevant for which release. If any information is only relevant for a particular release (past or future one) in should be clearly stated.    

Cross-cutting concerns

Relevant information not specific for a particular domain is documented within the IT general section. 

Deprecated / obsolete content

Content not relevant anymore is either deleted or moved into an Archive section of the Domain space.