Backend Service Fields

Within ArchRepo you can document multiple backend services for your solution. Each service is identified by an auto-generated reference (SVC-1, SVC-2, etc.) and can be linked to the APIs, data stores, streams, business processes, requirements, and non-functional requirements it relates to.

1. `Description`

What it’s for: A concise summary of what this backend service does and who or what uses it.
What to include:
- Describe the primary purpose of the service in plain language — what business capability does it fulfil?
- Identify the main consumers — which applications, services, or processes call this service?
- Note any important constraints or context (e.g. “internal only”, “stateless”, “owns the customer domain”, “replaces legacy billing component”).
Example: "Handles all customer profile management — creation, updates, retrieval, and deactivation. Called by the web portal, mobile app, and the notifications service. The authoritative source of customer data within the solution."

2. `External`

What it’s for: Indicates whether this backend service is external to the solution — i.e. operated by a third party or partner rather than built and owned internally.
What to include:
- Set to Yes for services you integrate with but do not control: SaaS platforms, partner services, managed cloud services (e.g. a third-party identity provider, a payment processing service).
- Set to No for services owned and operated within your solution.
- The external flag is significant for impact analysis: changes to external services are outside your control and may require your team to adapt reactively.

Relationships

Backend services support a rich set of relationships to other model items. Use these to build a complete picture of each service’s place in the solution.

APIs (Contains)

Link to the APIs that this service exposes to other consumers.
Use this to document the public interface of the service.

APIs (Uses)

Link to the APIs this service calls — whether internal APIs from other services or external third-party APIs.

Data Stores (Has Read / Write / Admin Access)

Link to the data stores this service reads from or writes to.
Use the access level that accurately reflects the service’s permissions:
- Has Read Access — read-only
- Has Write Access — write (and typically read)
- Has Admin Access — schema migrations, user management, or operational control

Streams (Receives / Generates)

Link to event streams or message queues this service receives messages from or generates messages to.
Captures the asynchronous communication patterns the service participates in.

Business Processes (Supports / Replaces)

Use Supports to trace which business processes this service enables.
Use Replaces to indicate that this service is replacing a manual or legacy business process.

Business Scenarios (Supports)

Link to the business scenarios this service participates in.

Business Rules (Implements)

Link to the business rules that this service enforces. This makes it traceable that a rule has been implemented in a specific service.

Business Requirements (Supports)

Link to the business requirements this service addresses.

Non-Functional Requirements (Supports)

Link to the non-functional requirements (NFRs) this service is expected to meet.

Architectural Quality Mechanisms

Link to the relevant quality mechanism items that describe how this service achieves its non-functional characteristics:

Observability — how the service is monitored, logged, and traced
Availability — how the service achieves its uptime targets
Recoverability — how the service recovers from failure
Performance — how the service meets its throughput and latency targets
Security — the security mechanisms applied to this service
Deployability — how the service is packaged, deployed, and updated

Technologies (Uses)

Link to the technologies used to build or operate this service (e.g. frameworks, runtimes, platforms).

Data Sets (Uses)

Link to any data sets that describe the data structures this service works with.

Business Information (Uses)

Link to high-level business information items relevant to this service.

Design Decisions (Supports)

Link to the architectural design decisions that shaped the design of this service.

Acceptance Criteria (Has)

Link to the Business Acceptance Criteria that this service must satisfy.

Implementation Acceptance Criteria (Has)

Link to the Implementation Acceptance Criteria relevant to this service’s delivery.

Risks, Assumptions, and Issues (Has)

Link to any risks, assumptions, or issues associated with this service.

Tasks (Has)

Add tasks to track the specification, design, or delivery work associated with this service.

Test Data (Has)

Link to test data items used to test this service.

Business Reference (Implements)

Link to any business reference items (e.g. frameworks, standards) that this service implements.