| 1 | # 0001 — Git lives at the root namespace, REST lives under `/api` |
| 2 | |
| 3 | **Status:** adopted |
| 4 | |
| 5 | ## Decision |
| 6 | |
| 7 | `app.setGlobalPrefix('/api')` with `:username/*path` excluded. Every REST route is |
| 8 | served from `/api/*`; the root namespace belongs to the git transport. |
| 9 | |
| 10 | ## Why |
| 11 | |
| 12 | `/:username/:repo/info/refs` is a greedy root-level route. Registered alongside |
| 13 | `/repositories`, it competes with every present and future REST path, and Nest |
| 14 | resolves the conflict by module registration order in `AppModule.imports`. That |
| 15 | is invisible in code review and breaks the moment someone reorders an import. |
| 16 | |
| 17 | GitHub draws the same line: `api.github.com` for REST, `github.com/user/repo.git` |
| 18 | for the transport. Better Auth already sits at `/api/auth`, so half the split |
| 19 | existed anyway. |
| 20 | |
| 21 | ## Alternatives rejected |
| 22 | |
| 23 | - **Serve git under a prefix** (`/git/:username/:repo`). Works, but `git clone` |
| 24 | URLs then carry a `/git` segment forever. The clone URL is user-facing product |
| 25 | surface; it should read `host/user/repo.git`. |
| 26 | - **Order routes carefully.** Correct today, fragile permanently. |
| 27 | |
| 28 | ## Consequences |
| 29 | |
| 30 | - `NEXT_PUBLIC_API_URL` consumers in `fetch-client.ts` target `/api`. |
| 31 | - `openapi.json` must be regenerated when the prefix changes. |
| 32 | - Any future root-level page route (`/settings`, `/explore`) is served by the web |
| 33 | app, not the API — the API's root namespace is reserved for git. |