# sassine/sdd-desafio architecture

> Architecture diagram of the GitHub repository sassine/sdd-desafio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sassine/sdd-desafio
- Repository: https://github.com/sassine/sdd-desafio

## Overview

#### Purpose and Delivery Model
This is a Spec-Driven Development challenge repository, not an implemented application. Participants fork it and produce a documented, traceable reimbursement-engine project. The central deliverable is the specification and its evidence trail; working code is secondary.

Core entry documents:
- `DESAFIO.md` defines the exercise and reimbursement-policy problem.
- `RUBRICA.md` defines evaluation criteria.
- `README.md` provides the workflow and required final repository shape.

#### Input and Domain Boundary
The reimbursement policy is intentionally ambiguous. The participant must derive explicit business rules, decisions, and acceptance criteria rather than seek clarification.

Reference input is:
- `exemplos/despesas-exemplo.json`

This JSON is the canonical sample expense dataset to inspect before designing rules, validations, classifications, reimbursement calculations, and expected outcomes.

#### Specification-First Workflow
The repository supplies a reusable project skeleton under:
- `template/specs/001-motor-reembolso/spec.md`
- `template/specs/001-motor-reembolso/plan.md`
- `template/specs/001-motor-reembolso/tasks.md`
- `template/specs/001-motor-reembolso/DECISIONS.md`

The intended flow is: interpret policy and sample data → write the product specification → select implementation design → decompose into numbered tasks with acceptance criteria → implement and test only against those tasks.

#### Decision and Change Control
Ambiguities are a first-class architectural input. Decisions must be explicit, justified, and retained in:
- `template/specs/001-motor-reembolso/DECISIONS.md`
- `template/specs/001-motor-reembolso/spec.md`

A mandatory Day-2 requirement change tests whether the specification can absorb changed policy without losing traceability. The decision log is the boundary between original requirements, interpretations, and later revisions.

#### Traceability and Execution Governance
Commits are governed by task IDs: no implementation commit should exist without a corresponding task. The required chain is specification → task → commit → test/result.

Agent collaboration conventions are seeded in:
- `template/CLAUDE.md`

Claude Code conversations must be exported and committed under the eventual `docs/sessions/` directory, making the reasoning process auditable alongside code and documents.

#### Expected Generated Project
After copying the template, the participant’s fork should add root-level `CLAUDE.md`, `specs/`, and `docs/`, then create `src/` and `tests/`. The final project is expected to expose a reimbursement engine, though this starter repository contains no runtime, source code, test framework, database, web service, or deployment infrastructure.

The final report is based on:
- `template/docs/RELATORIO.md`

It should connect the implemented outcome, specification decisions, changes, tests, commits, and exported sessions.

Main entry points: [`template/specs/001-motor-reembolso/spec.md`](https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/spec.md) (Product specification), [`template/specs/001-motor-reembolso/tasks.md`](https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/tasks.md) (Numbered tasks), [`template/specs/001-motor-reembolso/DECISIONS.md`](https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/DECISIONS.md) (Decision log), [`template/docs/RELATORIO.md`](https://github.com/sassine/sdd-desafio/blob/main/template/docs/RELATORIO.md) (Final report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_starter["Challenge Starter"]
  node_challenge["Challenge brief<br/>exercise definition<br/>[DESAFIO.md]"]
  node_rubric["Evaluation rubric<br/>assessment criteria<br/>[RUBRICA.md]"]
  node_readme["Workflow guide<br/>repository guide<br/>[README.md]"]
  node_sample_data["Sample expenses<br/>canonical input"]
  node_agent_conventions["Agent conventions<br/>collaboration guidance<br/>[CLAUDE.md]"]
end

subgraph group_spec["Specification Workflow"]
  node_template_spec["Product specification<br/>specification template<br/>[spec.md]"]
  node_decisions["Decision log<br/>ambiguity control<br/>[DECISIONS.md]"]
  node_plan["Implementation plan<br/>design template<br/>[plan.md]"]
  node_tasks["Numbered tasks<br/>execution plan<br/>[tasks.md]"]
end

subgraph group_delivery["Participant Delivery"]
  node_engine["Reimbursement engine<br/>participant implementation"]
  node_tests_results["Tests and results<br/>verification evidence"]
  node_commits["Task-linked commits<br/>change history"]
  node_sessions["Exported sessions<br/>reasoning audit trail"]
  node_report["Final report<br/>delivery evidence<br/>[RELATORIO.md]"]
end

node_challenge -->|"policy problem"| node_template_spec
node_rubric -.->|"evaluation expectations"| node_template_spec
node_readme -->|"required workflow"| node_template_spec
node_sample_data -->|"derive rules from"| node_template_spec
node_sample_data -->|"resolve ambiguities from"| node_decisions
node_template_spec -->|"records interpretations"| node_decisions
node_decisions -->|"revisions update"| node_template_spec
node_template_spec -->|"drives design"| node_plan
node_plan -->|"decomposes into"| node_tasks
node_template_spec -->|"acceptance criteria"| node_tasks
node_tasks -->|"authorizes implementation"| node_engine
node_tasks -->|"governs"| node_commits
node_engine -->|"verified by"| node_tests_results
node_tasks -->|"expected outcomes"| node_tests_results
node_agent_conventions -->|"requires export"| node_sessions
node_commits -->|"reported in"| node_report
node_tests_results -->|"reported in"| node_report
node_decisions -->|"reported in"| node_report
node_sessions -->|"audit evidence"| node_report

click node_challenge "https://github.com/sassine/sdd-desafio/blob/main/DESAFIO.md"
click node_rubric "https://github.com/sassine/sdd-desafio/blob/main/RUBRICA.md"
click node_readme "https://github.com/sassine/sdd-desafio/blob/main/README.md"
click node_sample_data "https://github.com/sassine/sdd-desafio/blob/main/exemplos/despesas-exemplo.json"
click node_template_spec "https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/spec.md"
click node_decisions "https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/DECISIONS.md"
click node_plan "https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/plan.md"
click node_tasks "https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/tasks.md"
click node_agent_conventions "https://github.com/sassine/sdd-desafio/blob/main/template/CLAUDE.md"
click node_report "https://github.com/sassine/sdd-desafio/blob/main/template/docs/RELATORIO.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_challenge,node_rubric,node_readme,node_sample_data,node_agent_conventions toneBlue
class node_template_spec,node_decisions,node_plan,node_tasks toneAmber
class node_engine,node_tests_results,node_commits,node_sessions,node_report toneMint
```

## Components

### Challenge Starter

Documents and templates supplied to participants.

- [Challenge brief](https://github.com/sassine/sdd-desafio/blob/main/DESAFIO.md): exercise definition · Defines the reimbursement-policy problem. · `DESAFIO.md`
- [Evaluation rubric](https://github.com/sassine/sdd-desafio/blob/main/RUBRICA.md): assessment criteria · Defines how the submission is evaluated. · `RUBRICA.md`
- [Workflow guide](https://github.com/sassine/sdd-desafio/blob/main/README.md): repository guide · Defines workflow and required final repository shape. · `README.md`
- [Sample expenses](https://github.com/sassine/sdd-desafio/blob/main/exemplos/despesas-exemplo.json): canonical input · Canonical dataset used to derive rules and expected outcomes. · `exemplos/despesas-exemplo.json`
- [Agent conventions](https://github.com/sassine/sdd-desafio/blob/main/template/CLAUDE.md): collaboration guidance · Seeds auditable Claude Code collaboration practices. · `template/CLAUDE.md`

### Specification Workflow

Traceable artifacts produced from policy interpretation.

- [Product specification](https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/spec.md): specification template · Captures rules, validations, classifications, and acceptance criteria. · `template/specs/001-motor-reembolso/spec.md`
- [Decision log](https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/DECISIONS.md): ambiguity control · Records interpretations, justifications, and policy revisions. · `template/specs/001-motor-reembolso/DECISIONS.md`
- [Implementation plan](https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/plan.md): design template · Selects the implementation design. · `template/specs/001-motor-reembolso/plan.md`
- [Numbered tasks](https://github.com/sassine/sdd-desafio/blob/main/template/specs/001-motor-reembolso/tasks.md): execution plan · Decomposes delivery into tasks with acceptance criteria. · `template/specs/001-motor-reembolso/tasks.md`

### Participant Delivery

Artifacts added in the completed fork.

- **Reimbursement engine**: participant implementation · Implements approved reimbursement policy behavior.
- **Tests and results**: verification evidence · Verifies implementation against task acceptance criteria.
- **Task-linked commits**: change history · Implementation commits must reference a corresponding task.
- **Exported sessions**: reasoning audit trail · Committed Claude Code conversations preserve reasoning evidence.
- [Final report](https://github.com/sassine/sdd-desafio/blob/main/template/docs/RELATORIO.md): delivery evidence · Connects outcome, decisions, changes, tests, commits, and sessions. · `template/docs/RELATORIO.md`

## Connections

- Challenge brief → Product specification: policy problem
- Evaluation rubric → Product specification: evaluation expectations
- Workflow guide → Product specification: required workflow
- Sample expenses → Product specification: derive rules from
- Sample expenses → Decision log: resolve ambiguities from
- Product specification → Decision log: records interpretations
- Decision log → Product specification: revisions update
- Product specification → Implementation plan: drives design
- Implementation plan → Numbered tasks: decomposes into
- Product specification → Numbered tasks: acceptance criteria
- Numbered tasks → Reimbursement engine: authorizes implementation
- Numbered tasks → Task-linked commits: governs
- Reimbursement engine → Tests and results: verified by
- Numbered tasks → Tests and results: expected outcomes
- Agent conventions → Exported sessions: requires export
- Task-linked commits → Final report: reported in
- Tests and results → Final report: reported in
- Decision log → Final report: reported in
- Exported sessions → Final report: audit evidence