# Project Structure and Deployment Layout Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Move backend runtime code under `backend/`, compiled frontend output under `dist/`, update all entry/configuration paths, and verify the application without touching production data.

**Architecture:** Keep backend-relative imports intact by moving backend directories and backend scripts as one unit. Keep `database/`, `migrations/`, `sql/`, and `tests/` at repository root as independent assets. Serve or deploy the compiled frontend from `dist/` and start the backend from `backend/finance.js`.

**Tech Stack:** Node.js, Express, Sequelize, MySQL, CommonJS, npm, Git.

**Spec:** `docs/superpowers/specs/2026-09-13-project-structure-design.md`

## Global Constraints

- Move backend runtime directories and entry scripts together so their internal relative imports remain valid.
- Move only compiled frontend files (`index.html`, `index_.html`, `assets/`, and related static root assets) into `dist/`.
- Keep database definitions and migrations outside `backend/`.
- Do not move, edit, or connect to the production database.
- Do not add `.env`, archives, logs, `Uploads/`, `node_modules/`, or generated duplicate build directories to Git.
- Verify module loading, test discovery, package scripts, and clean Git status before pushing.

---

### Task 1: Record baseline and create structural test coverage

**Files:**
- Create: `tests/projectStructure.test.js`

**Interfaces:**
- Produces assertions for the target paths and entrypoint expected by later tasks.

- [ ] **Step 1: Write the failing test**

```js
const assert = require("node:assert/strict");
const fs = require("node:fs");
const path = require("node:path");
const test = require("node:test");

const root = path.resolve(__dirname, "..");

test("backend runtime and frontend distribution use the target layout", () => {
  for (const relativePath of [
    "backend/finance.js",
    "backend/package.json",
    "dist/index.html",
    "dist/assets",
  ]) {
    assert.equal(fs.existsSync(path.join(root, relativePath)), true, relativePath);
  }
  assert.equal(fs.existsSync(path.join(root, "finance.js")), false);
  assert.equal(fs.existsSync(path.join(root, "index.html")), false);
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `node --test tests/projectStructure.test.js`
Expected: FAIL because the target directories do not exist yet.

- [ ] **Step 3: Commit the test**

Run: `git add tests/projectStructure.test.js && git commit -m "test: define target project layout"`

### Task 2: Move backend runtime files and frontend distribution files

**Files:**
- Create: `backend/` containing current backend runtime directories and scripts.
- Create: `dist/` containing compiled frontend files.
- Modify: `.gitignore`

**Interfaces:**
- Consumes the existing root layout.
- Produces `backend/finance.js` and `dist/index.html` without changing backend-internal relative paths.

- [ ] **Step 1: Create destination directories**

Run: `New-Item -ItemType Directory -Force backend, dist | Out-Null`

- [ ] **Step 2: Move backend runtime directories and files**

Move these root directories into `backend/`: `Config`, `controllers`, `Model`, `middlewares`, `routes`, `services`, `utils`, `scripts`, `seeders`, and `data`.

Move these root files into `backend/`: `finance.js`, `health-check.js`, `seed-shifts.js`, and `start-server.js`.

- [ ] **Step 3: Move compiled frontend output**

Move `index.html`, `index_.html`, `assets/`, `bg.jpg`, `logos.jpeg`, `manifest.json`, `placeholder.svg`, and `robots.txt` into `dist/`.

- [ ] **Step 4: Run the structural test**

Run: `node --test tests/projectStructure.test.js`
Expected: PASS for filesystem layout; package and entrypoint path updates remain for Task 3.

### Task 3: Update runtime configuration and package metadata

**Files:**
- Modify: `package.json`
- Modify: `start-server.js` (now `backend/start-server.js`)
- Create: `backend/package.json`
- Create: `backend/package-lock.json`

**Interfaces:**
- Root package scripts delegate to `backend/finance.js`.
- Backend package remains self-contained for backend deployment.

- [ ] **Step 1: Update root scripts and pkg paths**

Set root `main` to `backend/finance.js`; set `start` to `nodemon backend/finance.js`; set `start:prod` to `cross-env NODE_ENV=production node backend/finance.js`; update `pkg.assets` entries from root directories to `backend/<directory>/**/*`; and set the binary entry to `backend/finance.js`.

- [ ] **Step 2: Update backend launcher**

Change the launcher require from `require('./app.js')` to `require('./finance.js')`, preserving its existing port behavior and messages.

- [ ] **Step 3: Add backend package metadata**

Create `backend/package.json` by copying the runtime dependency set from the root package and use `finance.js` as its `main`, with `start` set to `node finance.js`. Generate its lockfile with `npm install --package-lock-only --ignore-scripts` from `backend/` only if npm accepts the existing dependency declarations without changing application source.

- [ ] **Step 4: Run package/config checks**

Run: `node -e "require('./backend/finance.js')"`
Expected: The module loads or reports only an expected database-environment connection issue; any missing-module or path error must be fixed before continuing.

Run: `node --test tests/projectStructure.test.js`
Expected: PASS.

### Task 4: Update frontend serving and deployment references

**Files:**
- Modify: `backend/finance.js`
- Modify: `.htaccess`
- Modify: `README.md`

**Interfaces:**
- Backend serves static frontend files from `dist/` if the current server contains static-file wiring.
- README documents separate backend and dist deployment commands and the database safety boundary.

- [ ] **Step 1: Locate static-file and frontend path references**

Run: `rg -n "static|index\.html|assets|dist|__dirname" backend .htaccess README.md`

- [ ] **Step 2: Update only references that point to the moved frontend**

Change static roots from `__dirname` or root-relative `assets` to `path.join(__dirname, "..", "dist")` where the code is now under `backend/`. Preserve API routes and database configuration unchanged.

- [ ] **Step 3: Add deployment README**

Document `npm install`, `npm start`, `npm run start:prod`, `backend/` as the Node deployment unit, `dist/` as the static deployment unit, and explicit instructions never to commit `.env` or production database dumps.

- [ ] **Step 4: Run the structure and path checks**

Run: `node --test tests/projectStructure.test.js`
Expected: PASS.

### Task 5: Full verification and GitHub push

**Files:**
- Modify: any files required by verification fixes only.

**Interfaces:**
- Produces a clean structural commit on `main` pushed to `origin/main`.

- [ ] **Step 1: Run the complete test command**

Run: `npm test`
Expected: Record the actual exit code and test result; do not claim success if the existing script still exits with its configured “no test specified” failure.

- [ ] **Step 2: Run direct Node test discovery**

Run: `node --test tests/**/*.test.js tests/**/*.test.mjs utils/**/*.test.js`
Expected: Record every failing test and fix only path/regression failures caused by the move.

- [ ] **Step 3: Verify excluded files**

Run: `git ls-files .env '*.zip' 'Uploads/*' 'logs/*' 'node_modules/*' 'assets_/*'`
Expected: no output.

- [ ] **Step 4: Verify Git state and commit**

Run: `git status --short` and `git diff --check`; then commit with `git add -A && git commit -m "chore: separate backend and frontend distribution"`.

- [ ] **Step 5: Push and verify remote**

Run: `git push -u origin main` followed by `git ls-remote --heads origin main`.
Expected: remote `main` resolves to the new structural commit SHA.