# Tech documentation - Template

- **Feature name:** Warp drive design
- **Author(s):** Mary Smith
- **Required Reviewers:**
- Technical Expert(s): _Someone with the most knowledge on the relevant
technologies, language or framework. This may be multiple people if there
are multiple technologies involved._
- Stakeholder: _Someone who will use or be affected by the project_
- Service Owner(s): _Owner(s) of the Services Affected._
- Design review team: `veyond-card/design-review` (automatically added)

# Summary

One paragraph explanation (a.k.a executive summary).

# Motivation

Why are we doing this?

# Requirements and scope

List all the requirements of the design in the following sections:

## Supported use cases

What use cases does it support? Think about the different users: Customers,
Customer Experience Team, Ops Team... and be explicit about it.

Link to an existing Product Requirements/Specs Doc doc if one exists for the project.

_Examples_:

- It must generate `Ecto.Schema` with embedded validations.
- As a Customer, I must be able to sync my statements to my ERP.
- Ops and Customer Experience teams must be able to issue cards for any active
customer.

## Expected outcomes

What are the expected outcomes? This can include success metrics.

_Examples_:

- 10% of customers use the new feature.
- RabbitMQ is deprecated in favor of this new infrastructure.

## Out of scope

What are the non goals? Be explicit.

_Examples_:

- The internal functioning of `Service B`, used in this design.
- Design for Feature X, that will be done at a later point and is not required
by the current design.

# Basic concept

ELI5 (Explain like I'm 5) style aimed for new hires.

# Detailed design

All the technical stuff.

Explain the flows, the general behaviors, the edge cases. You can use diagrams
and other charts.

## Services Affected

Explicitly list the services affected by the design.

**For System design doc, include the following sub-sections:**

## Domain Model

Describe the domain models that the System's business logic will manipulate and
expose.

Use Elixir `bdefstruct` like DSL:

defmodule NewService.Models.NewModel do
  @moduledoc "Description of this new model."

  # You can use enums like that
  enum Status do
      :active
    | :disabled
  end

  field :name, String.t
  field :description, String.t
  field :type, Type.t
end

## Contracts

Define the contracts exposed by this service.

Use Elixir `Micro.Contract` DSL:

defmodule NewService.Contracts.NewContract do
  @moduledoc "Description of this new contract."

  @doc "What does this endpoint do?"
  @callback my_function(arg1 :: String.t, opts :: Keyword.t) ::
              Brex.Result.s(MyNewModel.t)

  # ...
end

## GraphQL API (optional)

If the System exposes some of its data to the dashboard (through `api`),
describe here the GraphQL changes.

Use the GraphQL DSL:

my_new_models {
  name: String!
  description: String
  inserted_at: Time!
  num: Integer!
}

## Idempotence / Re-entrance

Explain in this section how the API exposed by the system designed is idempotent
or re-entrant, e.g. how is the idempotency key is generated by the client, how
it is used, etc.

## Persistent layout (optional)

If the System requires persisting data, define here how the System's data is
going to be persisted in the database.

It is assumed that a Postgres database is going to be used, but if it is not,
explain the choice of database used.

If the Domain models are 1-to-1 mapping to Data models, you can mention the ones
that are identical and the ones that differ.

You can either use Elixir `bdefstruct` like DSL or SQL statements.

## Supportability

- What pages/features should be added in our back-office (Retool) to support
this design? If any are required, describe them.
- Which team besides Engineering should be involved in the daily functioning of
the new System/feature?

_Example_:

- A new page will allow internal teams to issue new cards by selecting a
Customer Account first, and then a specific User.

Think about what can go wrong (not necessarily caught in logs), how issues will
be resolved, and by which team.

- If something bad happens, which team(s) will be notified?
- Is there any potential bugs that won't be caught in alerts/monitoring? e.g.
logic error, external providers failures, etc.
- If Customer Experience Team is notified by such bug, how should they proceed
to resolve the issue?
- Should a new Retool page be created to allow Customer Experience Team to
address customers issues directly, without engineers intervention?

_Examples_:

- It is possible that a transaction gets assigned to a wrong merchant category,
resulting in a wrong multiplier. Customer Experience Team can address such
issue by granting a one-off rewards to affected Customers.
- Customer may dispute a wrong collection. In such event, a Retool page will
list all the Collections initiated for the Customer Account with their status
associated. A button will allow cancelling scheduled collections to be able to
prevent further collections while the root issue is addressed.

# Drawbacks

Why we should **NOT** do this.

# Rationale and alternatives

Explain alternative solutions to the one described: why didn't we do them?

Why did we chose what we did considering the drawbacks if any?

# Testing

What are the main components to test? Describe the test plan: automated tests
(unit, integration, end-to-end), manual tests (if so, list the test cases),
ongoing QA (schedule)...

# Audit

What are the operations performed within the System, or triggered by it, that
should be audited?

# Logging Alerts

What are the list of critical operations/failures that should be logged and
trigger alerts?

Also mention what data fields are logged in such alerts.

# Unresolved questions

What is missing before this can be handed to `Random Joe` for implementation?

# Glossary

Explain here the domain specific or technical terms that a new hire would not
understand.