alla-allaos-fullstack/plans/task-d.7.11.md

Task D.7.11 – First-Run Bootstrap Setup Mode

Objective

Implement first-run setup mode for ALLA OS.

When the database is newly migrated and the system has not been initialized, the app must automatically redirect users to a public bootstrap setup page without requiring login.

The bootstrap setup page allows uploading required CSV files, validates them, commits setup data, creates the first organization and administrator, marks setup as completed, and then redirects the user to login.

---

Desired Flow

npm install npm run db:generate npm run db:migrate npm run dev

Open browser

If setup is not completed:

redirect to

/administration/setup

No login required.

User uploads CSV files:

• users.csv
• organizations.csv
• memberships.csv
• master-options.csv
• branches.csv
• product-types.csv
• document-sequences.csv
• approval-workflows.csv
• approval-steps.csv
• approval-matrix.csv
• customers.csv
• contacts.csv
• leads.csv
• opportunities.csv
• quotations.csv
• quotation-items.csv
• quotation-parties.csv
• quotation-topics.csv
• quotation-topic-items.csv

Click Setup

System validates CSV

System commits data

System creates first admin

System marks setup completed

Redirect to login

User logs in and starts using the system

---

Key Concept

There are now two setup modes:

1. Bootstrap Setup

Used before first login.

Route:

/administration/setup

No login required only when setup is not completed.

2. Admin Setup / Maintenance Setup

Used after login.

Route:

/dashboard/administration/setup

Requires super_admin.

---

Required Behavior

First Run Detection

Create setup status check:

System is not initialized when:

• no completed setup_run exists or
• no super_admin user exists or
• no organization exists or
• no admin membership exists

System is initialized when:

• setup_run status = completed
• at least one super_admin exists
• at least one organization exists
• admin membership exists

---

Middleware Redirect

Update middleware behavior:

If setup is not completed:

allow only:

/administration/setup /api/setup/bootstrap/* /api/setup/templates /_next/* static assets

redirect all other routes to:

/administration/setup

If setup is completed:

/administration/setup redirects to:

/auth/sign-in

or

/dashboard

---

Bootstrap Setup Page

Create:

src/app/administration/setup/page.tsx

This page must not use dashboard layout.

It should be a clean public setup page.

Show:

• System status
• Required CSV upload
• Template checklist
• Preview result
• Setup button
• Completion screen

---

Bootstrap APIs

Create public-but-guarded bootstrap APIs:

GET /api/setup/bootstrap/status

POST /api/setup/bootstrap/preview

POST /api/setup/bootstrap/commit

POST /api/setup/bootstrap/complete

These APIs do not require login only while setup is incomplete.

After setup is completed, these APIs must reject public access.

---

Bootstrap Security

Even though no login is required, it must be protected by first-run rules.

Rules:

• Bootstrap APIs are enabled only when setup is incomplete.
• Once completed, bootstrap APIs return 403.
• Commit requires previewHash.
• Commit re-runs preview.
• Commit rejects hash mismatch.
• Setup complete requires successful commit.
• Never expose secrets.
• Passwords from users.csv must be hashed.
• No raw CSV contents are persisted.

Optional safety:

Require BOOTSTRAP_SETUP_TOKEN from .env if present.

If env exists:

User must enter token before setup.

---

CSV Upload UX

The page should show required groups:

Foundation:

• users.csv
• organizations.csv
• memberships.csv
• master-options.csv
• branches.csv
• product-types.csv

Document / Approval:

• document-sequences.csv
• approval-workflows.csv
• approval-steps.csv
• approval-matrix.csv

Business optional:

• customers.csv
• contacts.csv
• leads.csv
• opportunities.csv
• quotations.csv
• quotation-items.csv
• quotation-parties.csv
• quotation-topics.csv
• quotation-topic-items.csv

Allow partial setup:

Required minimum:

• users.csv
• organizations.csv
• memberships.csv
• master-options.csv
• branches.csv
• product-types.csv
• document-sequences.csv
• approval-workflows.csv
• approval-steps.csv
• approval-matrix.csv

Business CSV can be optional.

---

Setup Completion

After successful commit:

• create setup_run completed
• create seed_manifests
• mark setup status completed
• redirect to /auth/sign-in

Show message:

Setup completed. Please login with the administrator account from users.csv.

---

Reuse Existing D.7 Work

Reuse:

• CSV templates from D.7.3
• CSV preview engine from D.7.4
• CSV commit engine from D.7.5
• setup state from D.7.8
• seed manifest from D.7.8
• plugin profiles from D.7.9

Do not rewrite import engine.

---

Out of Scope

• Dashboard setup redesign
• New CSV format
• Reset/reseed
• Plugin marketplace
• Production public setup after completed
• Anonymous setup after system is initialized

---

Acceptance Criteria

• Fresh database redirects to /administration/setup without login.
• /administration/setup works before first login.
• Bootstrap setup page can upload CSV files.
• Preview validates CSV files.
• Setup commit imports required setup data.
• First admin user is created.
• Organization is created.
• Setup run is marked completed.
• User is redirected to login.
• After completion, /administration/setup no longer allows public setup.
• After completion, dashboard setup requires super_admin.
• Existing /dashboard/administration/setup remains available for maintenance.
• No duplicate CSV validation/import logic is created.
• Typecheck passes.

---

Suggested Test

1. Drop/reset database.
2. Run migration.
3. Run dev server.
4. Open /.
5. Confirm redirect to /administration/setup.
6. Upload required CSV files.
7. Preview.
8. Commit setup.
9. Confirm redirect to login.
10. Login with admin from CSV.
11. Open dashboard.
12. Confirm CRM works.
13. Try opening /administration/setup again.
14. Confirm public setup is blocked.