Technology Stack

No frontend framework. No build step. Every choice is justified by simplicity, familiarity, and self-hostability.

Why no frontend framework?

The interactivity requirements for V1 — editable cells, dropdowns, column config popovers, an unsaved-changes flag — are well within Alpine's scope. Adding React or Vue would introduce a build step, a node_modules directory, and a component lifecycle to reason about, none of which are warranted here. Alpine keeps reactivity local and declarative without changing the HTML mental model.

Why HTMX alongside Alpine?

Alpine manages UI state. HTMX manages server communication. They have no overlap. HTMX's hx-post and hx-get replace fetch calls for loading and saving workspaces. Alpine handles everything that never needs to touch the server until save time.

File Structure

Webroot is /public. All data, config, and source lives outside it. PHP sessions handle auth; no .htaccess trickery needed for security if the server is configured correctly.

Storage Layer

Storage is abstracted behind a PHP interface from day one. The V1 implementation is flat JSON files. Swapping to SQLite or Supabase later requires only writing a new class — no changes to endpoints or templates.

The interface

interface WorkspaceStorage {
    public function list(string $userId): array;
    public function load(string $workspaceId): array;
    public function save(string $workspaceId, array $data): void;
    public function create(string $ownerId, string $name): array;
    public function delete(string $workspaceId): void;
}

FlatFileStorage — V1

Each workspace lives in its own subdirectory under data/workspaces/. The canonical state is always current.json. On every save, the previous current.json is copied into snapshots/ with a timestamped filename before being overwritten.

data/workspaces/
  ws_001/
    current.json
    snapshots/
      2026-03-01T10-00-00Z_v1.json
      2026-03-01T14-32-00Z_v2.json

Users file

A single data/users.json holds all user records. In V1, this file is hand-edited by the admin. No registration endpoint exists. The structure is:

[
  {
    "id": "usr_001",
    "email": "alice@example.com",
    "password_hash": "$2y$12$...",
    "display_name": "Alice"
  }
]

config.php

A single config file at the project root sets the data path and the active storage driver. Switching drivers in the future is a one-line change here.

define('DATA_PATH', __DIR__ . '/data');
define('STORAGE_DRIVER', 'flatfile'); // 'sqlite' | 'supabase'

Data Model

Every workspace is a single JSON document. The schema is designed to be human-readable and to support future workspace types beyond grid.

Full workspace document

{
  "workspace_id": "ws_001",
  "workspace_name": "Project Tracker",
  "workspace_owner": "usr_001",
  "authorized_users": ["usr_002"],
  "timestamp_created": "2026-03-01T10:00:00Z",
  "timestamp_lastedited": "2026-03-01T14:32:00Z",
  "workspace_type": "grid",
  "version": 3,

  "schema": {
    "columns": [
      {
        "id": "col_1",
        "name": "Task",
        "type": "text"
      },
      {
        "id": "col_2",
        "name": "Status",
        "type": "status",
        "options": [
          { "label": "To Do",       "color": "#e2e8f0" },
          { "label": "In Progress", "color": "#fef08a" },
          { "label": "Done",        "color": "#86efac" }
        ]
      },
      {
        "id": "col_3",
        "name": "Priority",
        "type": "status",
        "options": [
          { "label": "Low",    "color": "#dbeafe" },
          { "label": "High",   "color": "#fee2e2" }
        ]
      }
    ]
  },

  "rows": [
    {
      "id": "row_1",
      "cells": {
        "col_1": "Write documentation",
        "col_2": "In Progress",
        "col_3": "High"
      }
    },
    {
      "id": "row_2",
      "cells": {
        "col_1": "Deploy to production",
        "col_2": "To Do",
        "col_3": "High"
      }
    }
  ]
}

Key decisions

Authentication

Simple, stateful, and secure enough for a self-hosted personal tool. Email and bcrypt-hashed password. PHP sessions. No OAuth, no tokens, no registration UI in V1.

Login flow

The user visits /login.php. On POST, api/auth.php reads data/users.json, finds the matching email, and runs password_verify() against the stored bcrypt hash. On success, the user ID and email are written to $_SESSION and the user is redirected to /index.php. On failure, an error message is returned.

Session behavior

Adding users (V1)

Users are hand-written into data/users.json. The password hash is generated with PHP's password_hash($password, PASSWORD_BCRYPT). A tiny CLI helper script can be provided for this: php scripts/add-user.php alice@example.com mypassword.

App Layout

Two-panel shell. Sidebar always visible after login. Main panel loads workspaces via HTMX without full page reloads.

Page structure

+------------------+------------------------------------+
|  SIDEBAR         |  MAIN PANEL                        |
|                  |                                    |
|  CoWork          |  [ Workspace Name — editable ]     |
|  ─────────────   |                                    |
|  Project Tracker |  col1 ▾  col2 ▾  col3 ▾  [+col]   |
|  Design Notes    |  ──────────────────────────────    |
|  Sprint Board    |  text   ● Done   ● High   [+row]   |
|                  |  text   ● To Do  ● Low    [+row]   |
|  + Workspace     |                                    |
+------------------+------------------------------------+

Sidebar behaviors

Default workspace naming

When a new workspace is created without a name, the backend counts existing workspaces owned by the user and assigns the next available name: workspace 1, workspace 2, etc. The name is immediately editable in the main panel header.

Workspace Grid

A dynamic table with typed columns. Column and row count can be changed at any time with SVG icon buttons. Two column types: free text and status/label.

Grid rendering

The workspace is rendered as an HTML <table> from the workspace JSON. The Alpine component on the table wrapper holds the full workspace state object. All mutations (add row, delete row, edit cell, etc.) update this state object. Nothing is persisted until save.

Column header

Each <th> contains the column name (editable inline), a type indicator, and a small gear/settings icon that opens a column config popover. The popover lets the user rename the column, change its type, and — if type is status — edit the label options and their colors. A delete icon removes the column (with confirmation).

Column types

Add / delete rows and columns

An SVG + icon at the end of the header row adds a new column (defaults to text type). An SVG + icon at the bottom of the table adds a new row. Each row has a delete icon on the left (visible on hover). Each column header has a delete icon in its config popover. Row and column IDs are generated client-side as row_<timestamp> and col_<timestamp>.

Alpine state shape

Alpine.data('workspace', () => ({
  meta: { id, name, version, ... },
  schema: { columns: [...] },
  rows: [...],
  dirty: false,       // true when unsaved changes exist
  saving: false,      // true during save request
  lastSaved: null,    // timestamp of last successful save

  addRow() { ... },
  deleteRow(id) { ... },
  addColumn() { ... },
  deleteColumn(id) { ... },
  updateCell(rowId, colId, value) { ... },
  markDirty() { this.dirty = true; },
  save() { ... }      // posts to /api/workspace.php
}))

Saving & Versioning

Explicit save with a background autosave safety net every ten minutes. Unsaved-change detection with a leave-page warning. Full snapshots on every save.

Save mechanisms

Server-side save process

When api/workspace.php receives a save POST, it does the following in order: validate the session, validate the payload, read the current current.json, copy it to snapshots/<timestamp>_v<n>.json, increment the version in the incoming payload, write the new current.json, return a success response with the new version number and timestamp.

Snapshot naming

snapshots/
  2026-03-01T10-00-00Z_v1.json
  2026-03-01T14-32-00Z_v2.json
  2026-03-01T22-15-44Z_v3.json

The timestamp uses hyphens instead of colons to be filesystem-safe on all platforms. The version suffix is redundant with the timestamp but makes it human-readable at a glance. Rollback UI in V2 reads this directory, sorts by timestamp, and presents the list.

Save button states

Build Order

Each phase produces something that runs. No phase should require the next to be testable.

V2 Considerations

Decisions made in V1 that are specifically designed to make these features straightforward to add later.