refactor: cluster backend under backend/, ops under infra/ - #8
Merged
Conversation
The root tree had `app/` (Python backend module) sitting one letter away
from `apps/` (TypeScript packages monorepo) — two completely different
things, easy to confuse. Backend-orbiting files (alembic/, pytest.ini,
requirements.txt, tests/, Dockerfile, Dockerfile.cloudflare) were also
scattered at root, making it unclear which were repo-wide. Operational
config (nginx/, monitoring/, searxng/) was also at root with no
clustering.
This restructure:
- Moves app/ → backend/app/ (Python module name unchanged, so
`from app.X import Y` still works; uvicorn target stays
`uvicorn app.main:app` and is invoked from backend/ cwd).
- Moves alembic/, alembic.ini, pytest.ini, requirements.txt, tests/,
Dockerfile, Dockerfile.cloudflare into backend/.
- Moves nginx/, monitoring/, searxng/ into infra/.
The Python module path stays `app.X.Y` to avoid touching imports across
the 93-endpoint backend. No runtime behaviour changes.
Updates to live config:
- Dockerfiles use `backend/` prefix on host paths (build context stays
at repo root, where docker-compose runs).
- docker-compose.yml/.prod.yml/.quickstart.yml: `build: { context: .,
dockerfile: backend/Dockerfile }` and `./infra/{nginx,searxng}` mount
paths.
- workers/containers.toml: dockerfile path updated to
`../backend/Dockerfile.cloudflare`.
- .github/workflows/ci-cd.yml + deploy-cf.yml: lint/test/coverage paths
prefixed with `backend/`.
- Makefile: `make dev`, `make test`, `make migrate`, etc. now cd into
backend/.
- ecosystem.config.js: PM2 cwd=./backend, env_file=../.env.
- scripts/manage.sh: BACKEND_DIR var; cd "$BACKEND_DIR" before backend
operations. scripts/test.sh, run_rag_tests.sh, setup.sh, restore.sh:
cd into backend/ where pytest.ini + alembic.ini live.
Housekeeping:
- Delete .turbo/ daemon cache (already gitignored; was tracked
accidentally). No turbo.json in the repo.
- Consolidate scripts/setup_stripe.py + setup_stripe_plans.py — keep
the newer setup_stripe_plans.py content under the canonical filename
setup_stripe.py (docs already referenced setup_stripe.py).
Docs updates:
- ADR-0006 amendment Part 2 documents this restructure.
- docs/what-is-what.md: full repo map rewritten.
- docs/architecture.md: backend container references updated.
- docs/citation-envelope.md, docs/roadmap.md: implementation paths
reflect `backend/app/…`.
- ADRs 0001, 0002, 0010: file path mentions updated.
- README.md: repo tree updated.
apps/backend/.env was already left in the working tree by the previous
restructure PR; it is gitignored. Compare with root .env and remove
manually if redundant.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Eliminates two long-standing root-tree friction points:
app/vsapps/ambiguity. One letter apart, two completely different things (app/was the entire Python FastAPI backend;apps/is the TypeScript packages monorepo). Now:backend/(the backend) andapps/(the packages).alembic/,pytest.ini,requirements.txt,tests/,Dockerfile,Dockerfile.cloudflarewere each at root — orbital files with no clear ownership. Now all clustered underbackend/.nginx/,monitoring/,searxng/also at root. Now clustered underinfra/.New layout
```
unsearch/
├── backend/ # FastAPI backend — single source of truth
│ ├── app/ # Python module (
from app.X import Yunchanged)│ ├── alembic/ # Postgres migrations
│ ├── tests/ # pytest suite
│ ├── alembic.ini pytest.ini requirements.txt
│ ├── Dockerfile # Self-host image
│ └── Dockerfile.cloudflare # CF Containers image
├── apps/ # TypeScript / SDK packages (pnpm workspace)
├── workers/ # Cloudflare Workers edge
├── infra/ # Operational config
│ ├── nginx/ monitoring/ searxng/
├── docs/ scripts/
└── docker-compose*.yml # Build context = root; mount paths from infra/
```
What did NOT change
app.X.Y— no `from app.X` → `from backend.X` rewrites. The folderapp/now lives insidebackend/; uvicorn is invoked frombackend/soapp.main:appstill resolves.workers/,apps/,scripts/,docs/unchanged.What did change (paths only)
backend/Dockerfile,backend/Dockerfile.cloudflare): COPY paths prefixed withbackend/; build context stays at repo root../infra/nginx,./infra/searxng.workers/containers.toml: dockerfile path →../backend/Dockerfile.cloudflare..github/workflows/ci-cd.yml+deploy-cf.yml: all lint/test/coverage paths prefixed withbackend/.Makefile: `make dev`, `make test`, `make migrate`, etc. nowcd backendbefore backend operations.ecosystem.config.js(PM2): `cwd: './backend'`, `env_file: '../.env'`, `PATH: '../venv/bin:...'`.scripts/manage.sh: new `BACKEND_DIR=$PROJECT_DIR/backend`, `cd "$BACKEND_DIR"` before backend ops.scripts/{test,run_rag_tests,setup,restore}.sh: cd intobackend/wherepytest.ini+alembic.inilive.Housekeeping
.turbo/daemon cache — already in.gitignore, was tracked accidentally. Noturbo.jsonexists in the repo.scripts/setup_stripe.py+setup_stripe_plans.py— kept the newersetup_stripe_plans.pycontent (matches the current $19/49/149 pricing tiers) under the canonical filenamesetup_stripe.py. Existing docs that referencepython scripts/setup_stripe.pycontinue to work.Docs updated
backend/app/….cd backendormake.Risk
apps/backend/.envstill gitignored — manually remove after diff-comparing with root.env.Test plan
backend/,infra/, no root-levelapp/oralembic/ornginx/.backend/.backend/.ci-cd.ymlquality + tests +deploy-cf.ymlworker + container jobs.../backend/Dockerfile.cloudflare.