Skip to content

refactor: cluster backend under backend/, ops under infra/ - #8

Merged
Rakesh1002 merged 1 commit into
mainfrom
Rakesh1002/repo-reorg
May 28, 2026
Merged

refactor: cluster backend under backend/, ops under infra/#8
Rakesh1002 merged 1 commit into
mainfrom
Rakesh1002/repo-reorg

Conversation

@Rakesh1002

Copy link
Copy Markdown
Owner

Summary

Eliminates two long-standing root-tree friction points:

  1. app/ vs apps/ 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) and apps/ (the packages).
  2. Backend concerns scattered at root. alembic/, pytest.ini, requirements.txt, tests/, Dockerfile, Dockerfile.cloudflare were each at root — orbital files with no clear ownership. Now all clustered under backend/.
  3. Ops scattered at root. nginx/, monitoring/, searxng/ also at root. Now clustered under infra/.

New layout

```
unsearch/
├── backend/ # FastAPI backend — single source of truth
│ ├── app/ # Python module (from app.X import Y unchanged)
│ ├── 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

  • Python module path stays app.X.Y — no `from app.X` → `from backend.X` rewrites. The folder app/ now lives inside backend/; uvicorn is invoked from backend/ so app.main:app still resolves.
  • No wire format, no runtime behaviour, no public API surface. This is pure file system reorganization.
  • workers/, apps/, scripts/, docs/ unchanged.

What did change (paths only)

  • Dockerfiles (backend/Dockerfile, backend/Dockerfile.cloudflare): COPY paths prefixed with backend/; build context stays at repo root.
  • docker-compose.yml/.prod.yml/.quickstart.yml: `build: { context: ., dockerfile: backend/Dockerfile }`. nginx + searxng mount paths now ./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 with backend/.
  • Makefile: `make dev`, `make test`, `make migrate`, etc. now cd backend before 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 into backend/ where pytest.ini + alembic.ini live.

Housekeeping

  • Delete .turbo/ daemon cache — already in .gitignore, was tracked accidentally. No turbo.json exists in the repo.
  • Consolidate scripts/setup_stripe.py + setup_stripe_plans.py — kept the newer setup_stripe_plans.py content (matches the current $19/49/149 pricing tiers) under the canonical filename setup_stripe.py. Existing docs that reference python scripts/setup_stripe.py continue to work.

Docs updated

  • ADR-0006 amendment Part 2 — documents this restructure on top of the existing Part 1 (the apps/backend collapse).
  • docs/what-is-what.md — full repo map rewritten with new layout, glossary refreshed.
  • docs/architecture.md — backend container references updated.
  • docs/citation-envelope.md + docs/roadmap.md — implementation paths now backend/app/….
  • ADRs 0001, 0002, 0010 — file path mentions updated.
  • README.md — repo tree updated, development commands now use cd backend or make.

Risk

  • Production deploy: unaffected. CI workflows updated to reflect new paths. `deploy-cf.yml` and `ci-cd.yml` both target backend/ now.
  • Local dev: anyone with a checked-out branch will need to re-run `pnpm install` (workspace path moved) and use `make dev` / `make test` instead of bare `uvicorn` / `pytest`.
  • Working tree: apps/backend/.env still gitignored — manually remove after diff-comparing with root .env.

Test plan

  • `git pull origin main && ls` shows backend/, infra/, no root-level app/ or alembic/ or nginx/.
  • `pnpm install` succeeds at root.
  • `make dev` starts uvicorn from backend/.
  • `make test` runs the pytest suite from backend/.
  • `docker compose -f docker-compose.quickstart.yml up -d` brings up the stack.
  • CI green on ci-cd.yml quality + tests + deploy-cf.yml worker + container jobs.
  • `wrangler containers deploy --config workers/containers.toml` finds ../backend/Dockerfile.cloudflare.

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.
@Rakesh1002
Rakesh1002 merged commit bf4a0fa into main May 28, 2026
2 of 6 checks passed
@Rakesh1002
Rakesh1002 deleted the Rakesh1002/repo-reorg branch May 28, 2026 16:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant