Stack Overview

File Structure

aquarium-portal/
├── src/
│   ├── main.tsx                  # Vite entry
│   ├── App.tsx                   # Router: public site vs admin vs team login
│   ├── context/
│   │   └── AppContext.tsx        # Global state, loadAll(), setView()
│   ├── components/
│   │   ├── PublicSite.tsx        # Landing page (public)
│   │   ├── AdminLogin.tsx        # Password form
│   │   ├── AdminLayout.tsx       # Sidebar + outlet
│   │   ├── TeamLogin.tsx         # Employee phone+PIN login
│   │   └── admin/
│   │       ├── DashboardView.tsx
│   │       ├── JobsView.tsx
│   │       ├── CalendarView.tsx
│   │       ├── ClientsView.tsx
│   │       ├── EmployeesView.tsx
│   │       ├── EstimatesView.tsx
│   │       ├── InvoicesView.tsx
│   │       ├── ServiceRequestsView.tsx
│   │       ├── ReportsView.tsx
│   │       └── SettingsView.tsx
│   └── types.ts                  # TypeScript interfaces
├── worker/
│   └── index.ts                  # Cloudflare Worker — all API routes
├── public/
│   └── user-guide.html           # In-portal help guide (standalone HTML)
├── migrations/
│   └── 001_init.sql              # D1 schema init migration
├── wrangler.toml
├── vite.config.ts
└── package.json

Auth Flow

Admin auth: The login form POSTs the password to /api/auth/login. The Worker hashes the input with SHA-256 and compares against the stored hash in the settings table. On match, it returns a signed token (a timestamped hash). The frontend stores this token in localStorage and sends it as Authorization: Bearer <token> on every subsequent request. The Worker validates the token on all /api/admin/* routes.

Employee auth: The Team Login form POSTs phone + PIN to /api/auth/employee-login. The Worker looks up the employee by phone, hashes the PIN, and compares. On match it returns an employee token scoped to that employee ID. The employee token only grants access to /api/employee/* routes.

AppContext & State

All global state lives in src/context/AppContext.tsx. The context exposes:

• state — object containing jobs, clients, employees, estimates, invoices, requests, settings, adminView, selectedId
• loadAll() — fetches all collections from the API in parallel
• setView(view, id?) — dispatches SET_VIEW, setting adminView and selectedId

Pre-selection pattern (used in Jobs, Estimates, Invoices): when navigating from a client card, setView('jobs', jobId) sets selectedId. The target view uses a lazy initializer:

const preJob = state.selectedId
  ? (state.jobs.find(j => j.id === state.selectedId) ?? null)
  : null;
const [selected, setSelected] = useState<Job | null>(preJob);

For JobsView specifically, selectedId can be either a job ID (navigate to job) or an employee ID (filter by employee). The view distinguishes these by checking if the ID matches a job first.

D1 Database Schema

-- Settings (single row, id=1)
CREATE TABLE settings (
  id INTEGER PRIMARY KEY,
  business_name TEXT,
  business_phone TEXT,
  business_email TEXT,
  business_address TEXT,
  logo_base64 TEXT,
  service_types TEXT,          -- JSON array
  invoice_prefix TEXT,
  invoice_next_number INTEGER,
  blocked_days TEXT,           -- JSON array of day numbers
  admin_password_hash TEXT
);

-- Clients
CREATE TABLE clients (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT,
  phone TEXT,
  address TEXT,
  notes TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

-- Employees
CREATE TABLE employees (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  phone TEXT NOT NULL UNIQUE,
  pin_hash TEXT NOT NULL,
  created_at TEXT DEFAULT (datetime('now'))
);

-- Jobs
CREATE TABLE jobs (
  id TEXT PRIMARY KEY,
  client_id TEXT REFERENCES clients(id),
  employee_id TEXT REFERENCES employees(id),
  service_type TEXT,
  scheduled_date TEXT,
  scheduled_time TEXT,
  status TEXT DEFAULT 'scheduled',  -- scheduled | in_progress | completed | cancelled
  price REAL,
  notes TEXT,
  is_recurring INTEGER DEFAULT 0,
  recurrence_type TEXT,             -- weekly | monthly
  created_at TEXT DEFAULT (datetime('now'))
);

-- Estimates
CREATE TABLE estimates (
  id TEXT PRIMARY KEY,
  client_id TEXT REFERENCES clients(id),
  status TEXT DEFAULT 'draft',      -- draft | sent | approved | declined
  line_items TEXT,                  -- JSON array [{desc, amount}]
  subtotal REAL,
  notes TEXT,
  expiry_date TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

-- Invoices
CREATE TABLE invoices (
  id TEXT PRIMARY KEY,
  client_id TEXT REFERENCES clients(id),
  invoice_number TEXT,
  status TEXT DEFAULT 'unpaid',     -- unpaid | paid
  line_items TEXT,                  -- JSON array [{desc, amount}]
  subtotal REAL,
  paid_at TEXT,
  notes TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

-- Service Requests
CREATE TABLE service_requests (
  id TEXT PRIMARY KEY,
  name TEXT,
  email TEXT,
  phone TEXT,
  service_type TEXT,
  message TEXT,
  status TEXT DEFAULT 'new',        -- new | converted
  created_at TEXT DEFAULT (datetime('now'))
);

API Routes

All routes are handled in worker/index.ts. The Worker is deployed at xyzaquarium-api.sonandigital.com.

Key Patterns

PDF generation: Estimates and invoices render into a hidden <div> with class print-only. The print CSS hides everything else. window.print() triggers the browser's PDF dialog. No server-side rendering required.

Logo storage: Logos are stored as base64 strings in the settings.logo_base64 column. On the frontend, they render as <img src={settings.logo_base64}> directly. Uploading fires a FileReader, converts to base64, and PUTs to /api/admin/settings.

Recurring jobs: When a job is created with is_recurring = 1, the Worker generates N future instances (weekly: 12 weeks, monthly: 6 months) as separate job rows at creation time. There is no background scheduler — all recurrences are materialized immediately.

CORS: The Worker sets Access-Control-Allow-Origin: https://xyzaquarium.sonandigital.com on all responses. In development, it allows http://localhost:5173. The ENVIRONMENT var controls which origin is allowed.

Theme & Styling

All colors are CSS custom properties defined in src/main.tsx (injected into :root). No hardcoded hex values in components.