From f17df1ec6b0f4ac6049b2c5ea603915a9dcba120 Mon Sep 17 00:00:00 2001 From: Hardik Date: Fri, 19 Jun 2026 12:12:04 +0530 Subject: [PATCH] docs: update design docs to the actual self-hosted architecture The original design docs assumed Vercel + Supabase + GitHub Actions. Reality is a single self-hosted pms1 server (Next.js under pm2, native PostgreSQL 16, Forgejo Actions runner, Pangolin/Traefik tunnel). - 02-architecture.md: CI/CD + Hosting rows, deployment diagram (section 10), CI/testing note, branch strategy, and secrets location. - e2e-test-plan.md / e2e-test-framework.md: GitHub Actions -> Forgejo Actions. - 03-open-questions.md: drop the Vercel-serverless aside. Co-Authored-By: Claude Opus 4.8 --- Docs/02-architecture.md | 67 +++++++++++++++++++++++--------------- Docs/03-open-questions.md | 2 +- Docs/e2e-test-framework.md | 2 +- Docs/e2e-test-plan.md | 6 ++-- 4 files changed, 45 insertions(+), 32 deletions(-) diff --git a/Docs/02-architecture.md b/Docs/02-architecture.md index 1824971..f00147d 100644 --- a/Docs/02-architecture.md +++ b/Docs/02-architecture.md @@ -21,8 +21,8 @@ The portal is an internal line-of-business app with a well-defined data model, m | **Charts** | Recharts | Lightweight; composable; works well with server-fetched data in RSC | | **Validation** | Zod | Schema validation shared between server actions and client form validation | | **Testing** | Vitest + React Testing Library + Playwright | Unit/integration fast with Vitest; E2E critical paths with Playwright | -| **CI/CD** | GitHub Actions | Lint, type-check, test, build on every PR; deploy on merge to main | -| **Hosting** | Vercel (app) + Supabase (Postgres + Storage fallback) | Zero-config deploys; Vercel serverless functions match Next.js well | +| **CI/CD** | Forgejo + Forgejo Actions (self-hosted on the `pms1` server) | Issue→fix→PR pipeline; a release tag (`vX.Y.Z`) triggers a runner that deploys. See [`../automation/README.md`](../automation/README.md) | +| **Hosting** | Self-hosted on `pms1` (Ubuntu); Next.js under **pm2**, **PostgreSQL 16** native on the same host; fronted by a Pangolin/Traefik tunnel | Single-VM self-host, no external PaaS; full control of data | --- @@ -497,31 +497,42 @@ All other data operations (create PO, approve, reject, etc.) are Server Actions ## 10. Deployment Architecture +The app is **self-hosted on a single server (`pms1`, Ubuntu)** — not a managed PaaS. +Public traffic reaches it through a Pangolin/Traefik tunnel; the Next.js app, database, +and the CI runner all live on the same host. + ``` -┌────────────────────────────────────────────────┐ -│ Vercel │ -│ │ -│ ┌──────────────────────────────────────────┐ │ -│ │ Next.js App (Edge + Node.js) │ │ -│ │ - Static assets via Vercel CDN │ │ -│ │ - Server Components on Node.js runtime │ │ -│ │ - API routes / Server Actions │ │ -│ └──────────────────────────────────────────┘ │ -└────────────────────────────────────────────────┘ - │ │ -┌────────▼──────┐ ┌────────▼──────────────┐ -│ Supabase │ │ Cloudflare R2 │ -│ PostgreSQL │ │ (document storage) │ -│ (managed, │ │ │ -│ auto-backup)│ └────────────────────────┘ -└───────────────┘ - │ -┌────────▼──────┐ -│ Resend │ -│ (email API) │ -└───────────────┘ + Internet (HTTPS, pms.pelagiamarine.com) + │ + ┌───────────▼────────────┐ + │ Pangolin / Traefik │ reverse proxy + tunnel + └───────────┬────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ pms1 (Ubuntu) │ +│ │ +│ ┌──────────────────────────┐ ┌────────────────────────┐ │ +│ │ Next.js app (pm2: ppms) │ │ PostgreSQL 16 (native, │ │ +│ │ `next start`, port 3000 │──▶│ localhost:5432, db │ │ +│ │ Server Components/Actions│ │ `pelagia`) │ │ +│ └──────────────────────────┘ └────────────────────────┘ │ +│ │ │ +│ ├─▶ Cloudflare R2 (document storage, prod) │ +│ └─▶ Resend (email, prod) │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Forgejo (Docker) + Actions runner (pm2) │ │ +│ │ issue→fix→PR→tag deploy — see automation/README.md │ │ +│ │ Also: pelagia_test (prod-mirror DB) + staging │ │ +│ └──────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ ``` +**Deploy flow:** merge a PR to `master`, push a release tag `vX.Y.Z` → a Forgejo +Actions runner checks out the tag into `~/pms`, runs `pnpm install && pnpm build && +prisma migrate deploy`, and `pm2 restart ppms`. Full runbook in +[`../automation/README.md`](../automation/README.md). + ### Environment Variables The set of required variables differs between development and production. The switch is automatic — controlled by `NODE_ENV` (set to `development` by `next dev` and `production` by `next build/start`). @@ -553,14 +564,16 @@ In development, uploaded files are stored in `.dev-uploads/` at the project root | E2E | Playwright | Full happy paths per role: create PO → approve → pay → confirm receipt | | Accessibility | axe-core + Playwright | WCAG violations on key pages | -CI runs all tests on every pull request. Playwright E2E runs against a preview deployment. +Tests run on pull requests via Forgejo Actions. Automated fixes and the staging instance +run integration tests / a dev server against `pelagia_test`, a daily mirror of the +production database (see [`../automation/README.md`](../automation/README.md)). --- ## 12. Development Conventions -- **Branch strategy**: `main` (production) ← `staging` ← feature branches (`feat/`, `fix/`, `chore/`). +- **Branch strategy**: `master` is the trunk and the source of releases. Work lands via PRs (feature branches `feat/`/`fix/`/`chore/`, or `claude/issue-N` from the automated pipeline); production is whatever `vX.Y.Z` tag is currently deployed. Staging is a deployed instance of latest `master`, not a branch. - **Commit style**: Conventional Commits (`feat:`, `fix:`, `refactor:`). - **Code quality**: ESLint (Next.js config) + Prettier + TypeScript strict mode; enforced via husky pre-commit hook. - **Database migrations**: Never edit `schema.prisma` without generating and committing a migration (`prisma migrate dev`). Migration files are committed and reviewed in PRs. -- **Secrets**: Never committed; managed via Vercel environment variable UI and `.env.local` locally (`.env.local` is git-ignored). +- **Secrets**: Never committed. On the server they live in `~/pms/App/.env` / `.env.production`; locally in `.env.local` (git-ignored). diff --git a/Docs/03-open-questions.md b/Docs/03-open-questions.md index b9e7a20..a0be0e3 100644 --- a/Docs/03-open-questions.md +++ b/Docs/03-open-questions.md @@ -12,5 +12,5 @@ Track decisions that need sign-off before the corresponding feature is built. Up | 6 | Should rejected POs be hard-deleted after a retention period or permanently archived? How long is the retention window? | Legal / compliance | Open | — | | 7 | Should documents (PO attachments, receipts) be publicly accessible via URL, or always served through a signed/authenticated download? | Security review | Open | — | | 8 | Are there specific vessels or accounts that certain submitters are restricted to (i.e., row-level vessel permissions), or is any submitter able to raise a PO against any vessel? | Design review | Open | — | -| 9 | What is the expected volume? (POs per day, concurrent users) — affects connection-pool sizing and whether Vercel serverless is sufficient. | Architecture review | Open | — | +| 9 | What is the expected volume? (POs per day, concurrent users) — affects connection-pool sizing and `pms1` resourcing. | Architecture review | Open | — | | 10 | Should Manager analytics (spend by vessel/month) include only CLOSED POs, or all POs from MGR_APPROVED onwards? | Design review | Open | — | diff --git a/Docs/e2e-test-framework.md b/Docs/e2e-test-framework.md index a9a4c73..94e9a15 100644 --- a/Docs/e2e-test-framework.md +++ b/Docs/e2e-test-framework.md @@ -302,7 +302,7 @@ HTML report at `playwright-report/index.html` after every run. ambiguous elements (unit price input, line-item rows) so specs don't depend on implementation details like placeholder text or CSS class names. -4. **CI integration** — Run `pnpm test:e2e` in GitHub Actions on every PR. +4. **CI integration** — Run `pnpm test:e2e` in Forgejo Actions (runner on `pms1`) on every PR. Use `workers: 1` and `retries: 2` (already wired for `process.env.CI`). 5. **Visual regression** — Add Percy or Playwright's built-in screenshot comparison diff --git a/Docs/e2e-test-plan.md b/Docs/e2e-test-plan.md index 3421959..b4198df 100644 --- a/Docs/e2e-test-plan.md +++ b/Docs/e2e-test-plan.md @@ -218,10 +218,10 @@ The following areas are not yet covered by automated E2E tests: ## 9 · Continuous Integration (Planned) -When wired into CI (GitHub Actions), the following configuration applies: +When wired into CI (Forgejo Actions, runner on `pms1`), the following configuration applies: ```yaml -# .github/workflows/e2e.yml +# .forgejo/workflows/e2e.yml - name: Install Playwright browsers run: pnpm exec playwright install --with-deps chromium @@ -229,7 +229,7 @@ When wired into CI (GitHub Actions), the following configuration applies: run: pnpm test:e2e env: CI: "true" - DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }} + DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }} # e.g. the pelagia_test mirror NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }} NEXTAUTH_URL: "http://localhost:3000" ```