# Planexa — administrator deployment handoff

This package contains the complete Planexa application source, database migrations, public assets, tests, and lockfile. It does **not** contain passwords or private API keys.

## Recommended production stack

- Application: Cloudflare Workers (the project uses `vinext` and Cloudflare runtime APIs)
- File storage: Cloudflare R2, binding name `FILES`
- Authentication and database: Supabase
- Node.js: 22.13 or newer
- Package manager: pnpm

Traditional static-only cPanel hosting is not sufficient because Planexa has server APIs, authentication, database access, and R2 file storage. A cPanel server can host it only after a developer replaces the Cloudflare-specific runtime and storage code. The shortest supported deployment is Cloudflare Workers + Supabase.

## Package contents

- `app/`: pages, dashboard, authentication screens, and server API routes
- `lib/`: authentication, exports, invoice PDF, Excel, and scheduling logic
- `supabase/migrations/`: complete Supabase database schema and security policies
- `public/`: logo, favicon, and social assets
- `worker/`: Cloudflare Worker entry point
- `deployment.env.example`: required environment-variable template
- `package.json` and `pnpm-lock.yaml`: exact dependencies
- `tests/`: automated scheduler and rendered-page checks

## 1. Prepare Supabase

1. Create a Supabase project, or use the existing Planexa Supabase project if the owner gives access.
2. Open SQL Editor and run every file in `supabase/migrations/` in numeric order, from `001` through `008`.
3. In Authentication, enable Email/Password.
4. Set the production Site URL and add these redirect URLs:
   - `https://YOUR-DOMAIN/auth/callback`
   - `https://YOUR-DOMAIN/login`
5. Obtain:
   - Project URL
   - Publishable/anon key
   - Service-role key (server secret; never expose it in browser code or commit it)

If the existing Supabase project is reused, existing users, clients, plans, tasks, attendance, and team data remain available. A brand-new Supabase project starts with no business data.

## 2. Prepare Cloudflare

1. Create or select a Cloudflare account.
2. Create an R2 bucket for Planexa files and records.
3. Bind that bucket to the Worker with the binding name `FILES`.
4. Enable the Worker assets binding expected by the vinext build.
5. Add the production environment variables listed below as encrypted Worker secrets/settings.

## 3. Environment variables

Copy `deployment.env.example` to `.env.local` for local development. Set the same values in the production host:

```text
NEXT_PUBLIC_SUPABASE_URL=https://YOUR-PROJECT.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR-PUBLISHABLE-KEY
SUPABASE_SERVICE_ROLE_KEY=YOUR-SERVICE-ROLE-KEY
NEXT_PUBLIC_GOOGLE_CLIENT_ID=OPTIONAL-GOOGLE-OAUTH-CLIENT-ID
```

`NEXT_PUBLIC_GOOGLE_CLIENT_ID` is optional unless Google OAuth/Google Sheets integration will be used.

## 4. Install and validate

```bash
corepack enable
pnpm install --frozen-lockfile
pnpm run test:unit
pnpm run build
```

The build must complete successfully before deployment. Verify `/api/health` after deployment.

## 5. Deploy

Use a Cloudflare Workers-compatible deployment pipeline for the generated vinext output. The deployment must provide:

- Cloudflare Worker-compatible ESM runtime
- R2 binding named `FILES`
- Static assets binding
- All environment variables from section 3
- Node.js compatibility flag

Connect the final custom domain in Cloudflare, then update Supabase Authentication URL Configuration with that exact HTTPS domain.

## 6. First administrator

For a new Supabase project, create the first user in Supabase Authentication. Copy the user's UUID and run:

```sql
insert into public.profiles (id, full_name, role, workspace_role, active)
values ('AUTH-USER-UUID', 'Administrator Name', 'admin', 'admin', true);
```

After the first admin can sign in, further team accounts can be created from Planexa's Team section.

## 7. Production acceptance checklist

- Homepage loads on HTTPS.
- `/dashboard` redirects unauthenticated visitors to `/login`.
- Admin can sign in and sign out.
- Client create/edit/delete and optional agreement upload work.
- Team account creation and module permissions work.
- Monthly task generation, reassignment, drag/reschedule, and completion work.
- Office location, check-in, and check-out work with browser location permission.
- Cash-flow records persist and Excel downloads correctly.
- Invoice generation shows Print, Download, and Both actions.
- `/api/health` reports healthy.

## Security handoff

Send this ZIP separately from secrets. Grant the administrator access to Cloudflare and Supabase through their own email/account instead of sending master passwords. Rotate the service-role key if it has ever been shared in an insecure channel.