[codex] Add architecture decision records

adr/0001-use-stellar-soroban.md

@@ -0,0 +1,45 @@
+# ADR-0001: Use Stellar Soroban for bounty contracts
+
+## Status
+
+Accepted
+
+## Context
+
+TaskBounty needs a smart-contract platform that can hold rewards in escrow, process approvals and refunds, and keep the full task lifecycle transparent for contributors and task posters.
+
+The platform should also be approachable for a small team building in Rust and should not make low-value bounties economically impractical through transaction fees.
+
+## Decision
+
+Use Stellar Soroban as the smart-contract runtime for the TaskBounty contract system.
+
+## Rationale
+
+- Soroban supports Rust-based contract development, which fits the repository's contract implementation.
+- Stellar transaction costs are low enough to keep smaller bounty flows viable.
+- Fast finality improves the user experience for submissions, approvals, and payout confirmation.
+- Native asset support and token interfaces make it practical to handle XLM and compatible Stellar assets.
+
+## Alternatives Considered
+
+### Ethereum mainnet
+
+- Pros: mature ecosystem, familiar contract patterns
+- Cons: higher transaction costs would make small task payouts harder to justify
+
+### Centralized escrow service
+
+- Pros: simpler operational model at the start
+- Cons: undermines the trustless payout goal and introduces custodial risk
+
+### Non-blockchain task board
+
+- Pros: lowest implementation complexity
+- Cons: does not satisfy the project's core goal of transparent, trust-minimized rewards
+
+## Consequences
+
+- Contributors should expect blockchain-specific concepts such as token addresses, finality, and wallet signing to remain central to the design.
+- Contract changes need careful review because core business rules live on-chain.
+- Tooling and local setup depend on Soroban and the Stellar CLI.

adr/0002-on-chain-escrow.md

@@ -0,0 +1,37 @@
+# ADR-0002: Keep reward escrow in the smart contract
+
+## Status
+
+Accepted
+
+## Context
+
+TaskBounty exists to reduce trust requirements between the task poster and the contributor. If funds remain fully off-chain until manual payout, contributors still face counterparty risk even if task tracking is public.
+
+## Decision
+
+Escrow the reward in the smart contract at task creation time and release or refund funds through contract-controlled flows.
+
+## Rationale
+
+- It gives contributors stronger assurance that the reward exists before they start work.
+- Approval, rejection, cancellation, and dispute outcomes can be enforced consistently by contract logic.
+- Escrow state can be audited on-chain instead of relying on manual bookkeeping.
+
+## Alternatives Considered
+
+### Off-chain payment after completion
+
+- Pros: simpler implementation
+- Cons: weak payout guarantees and more room for disputes over whether funds were ever reserved
+
+### Hybrid escrow with a centralized admin wallet
+
+- Pros: more operational flexibility
+- Cons: introduces an extra trusted actor and operational security burden
+
+## Consequences
+
+- Task creation must validate and transfer reward funds up front.
+- Contract APIs and events need to make escrow state transitions explicit.
+- Bugs in payout logic have direct financial implications and should be treated as high-risk changes.

adr/0003-separate-contract-and-frontend.md

@@ -0,0 +1,37 @@
+# ADR-0003: Separate contract and frontend workspaces
+
+## Status
+
+Accepted
+
+## Context
+
+The repository includes both Soroban contracts and a Next.js frontend. These parts move at different speeds, use different toolchains, and are validated with different commands.
+
+## Decision
+
+Keep the smart contract and frontend as separate workspaces within a single repository.
+
+## Rationale
+
+- Rust and Next.js have distinct dependency graphs and build pipelines.
+- Contributors can work on one surface without needing to understand every detail of the other immediately.
+- A monorepo still makes it easier to evolve interfaces, docs, and deployment guidance together.
+
+## Alternatives Considered
+
+### Single merged application workspace
+
+- Pros: fewer top-level directories
+- Cons: blurs ownership boundaries and makes tooling harder to reason about
+
+### Separate repositories
+
+- Pros: stronger isolation
+- Cons: harder cross-repo coordination for interface changes and contributor onboarding
+
+## Consequences
+
+- Documentation should clearly point contributors to the right workspace for their changes.
+- Shared concepts such as contract IDs and network configuration must be documented carefully at the repository root.
+- CI may need contract-specific and frontend-specific checks instead of one universal pipeline.

adr/0004-multiple-submissions-and-disputes.md

@@ -0,0 +1,39 @@
+# ADR-0004: Support multiple submissions with dispute resolution
+
+## Status
+
+Accepted
+
+## Context
+
+TaskBounty is not just a one-to-one freelance workflow. A bounty board can attract competing contributors, partial submissions, and disagreements about whether work meets the task requirements.
+
+The repository already models submissions and dispute handling, which means contributors need a clear statement of why the system is intentionally more flexible than a single-winner happy path.
+
+## Decision
+
+Support multiple submissions per task and provide an explicit dispute-resolution path when approval cannot be resolved directly between the poster and contributor.
+
+## Rationale
+
+- Competitive submissions are common in bounty-style systems.
+- Disputes are inevitable when work quality, deadlines, or acceptance criteria are ambiguous.
+- A defined dispute path makes the payout lifecycle more predictable than ad hoc moderator intervention.
+
+## Alternatives Considered
+
+### Single submission per task
+
+- Pros: simpler storage and approval logic
+- Cons: less aligned with bounty-board behavior and reduces contributor flexibility
+
+### Poster-controlled finality with no dispute process
+
+- Pros: smallest implementation surface
+- Cons: contributors have weaker protection against unfair rejection
+
+## Consequences
+
+- Storage and event models must track more than one submission per task.
+- Approval and refund logic must account for unresolved or contested states.
+- Frontend flows should expose status changes clearly so contributors understand whether a task is open, in review, approved, rejected, or disputed.

adr/README.md

@@ -0,0 +1,17 @@
+# Architecture Decision Records
+
+This directory documents important architecture decisions for TaskBounty.
+
+Each ADR captures:
+
+- the context behind the decision
+- the chosen approach
+- trade-offs and alternatives considered
+- the practical consequences for future contributors
+
+## Index
+
+- [ADR-0001: Use Stellar Soroban for bounty contracts](./0001-use-stellar-soroban.md)
+- [ADR-0002: Keep reward escrow in the smart contract](./0002-on-chain-escrow.md)
+- [ADR-0003: Separate contract and frontend workspaces](./0003-separate-contract-and-frontend.md)
+- [ADR-0004: Support multiple submissions with dispute resolution](./0004-multiple-submissions-and-disputes.md)