# ADR-0001: Repository structure

* **Status:** Accepted
* **Date:** 2026-05-22
* **Deciders:** Owner (Hamdan) + Lead Web3 Engineer
* **Supersedes:** —

## Context

The DevSwap Master Execution Prompt (v2) assumes a monorepo layout (`apps/web`, `packages/contracts`, `packages/subgraph`, …) and instructs the agent to read the structure before writing rather than assume it.

The repository already exists and is **live**:

* `web/` is deployed on Vercel with **Root Directory = `web`** and git auto-deploy connected to `main`. The custom domain `devswap.pro` resolves through Cloudflare → Vercel to this project.
* `contracts/` is a self-contained Foundry project (`foundry.toml`, `remappings.txt`, vendored `lib/`) with three CI workflows referencing these paths.
* `subgraph/`, `keeper/`, `notifications/`, `supabase/`, `cloudflare/` are independent workspaces, each with its own toolchain and lockfile.

There is **no root `package.json`** and no workspace manager. The repo is a "poly-folder" of independent projects, not an npm/pnpm workspace.

## Decision

**Keep the existing flat structure.** Do not restructure to `apps/*` + `packages/*`.

Map the prompt's intended layout onto the existing folders:

| Prompt (assumed)         | This repo (actual)         |
| ------------------------ | -------------------------- |
| `apps/web`               | `web/`                     |
| `packages/contracts`     | `contracts/`               |
| `packages/subgraph`      | `subgraph/`                |
| `services/keeper`        | `keeper/`                  |
| `services/notifications` | `notifications/`           |
| `infra/*`                | `cloudflare/`, `supabase/` |
| `docs/`                  | `docs/`                    |

## Consequences

**Positive**

* Live Vercel deploy (`rootDirectory=web`) keeps working with zero config churn.
* Foundry paths, remappings, vendored `lib/`, and the three CI workflows (`contracts.yml`, `security.yml`, `web.yml`) stay valid.
* The live domain and SSL chain are untouched.
* No risk of a large, untestable "move everything" diff before Phase 1 work.

**Negative / trade-offs**

* No shared `packages/*` for cross-app code reuse (e.g. a shared ABI/types package). Mitigation: the subgraph and web each keep their own copy of the ABI; the contract address + ABI are the only shared surface and are small.
* Cross-cutting scripts must be run per-folder (each has its own lockfile).

**Revisit when:** a genuine need for shared TypeScript packages appears (e.g. a shared `@devswap/contracts-types` consumed by both `web/` and `keeper/`). At that point introduce a pnpm workspace incrementally without moving `web/`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.devswap.pro/architecture-decisions/adr-0001-structure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.