From c86b950a0daa6225a211d29b9ee75c1d9ce986a5 Mon Sep 17 00:00:00 2001 From: jason Date: Wed, 22 Apr 2026 22:34:52 -0500 Subject: [PATCH] explainer file --- PROJECT.md | 255 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 PROJECT.md diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..f5d4911 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,255 @@ +# CODEDUMP + +Internal dashboard for tracking AI tools and coding projects. Provides a high-level overview of what the team is building, what tools are available, and the completion status of active work — all in one place. + +--- + +## Purpose + +CODEDUMP gives teams a single place to: + +- Track AI tools and coding projects with completion percentages +- Attach markdown documentation and project files +- Link to internal/external URLs and Google Drive sources +- Highlight new tools available to the team +- Manage access via admin accounts and 4-digit user PINs + +--- + +## Tech Stack + +| Layer | Technology | +|---|---| +| Frontend | React 18 + TypeScript + Vite | +| Styling | Tailwind CSS (dark mode, CSS variable theming) | +| Backend | Node.js + Express + TypeScript | +| Database | SQLite via `better-sqlite3` | +| Auth | JWT (12h expiry) + bcryptjs (admin passwords) + HMAC-SHA256 (user PINs) | +| File uploads | Multer (local disk storage) | +| Markdown | `react-markdown` + `remark-gfm` | +| Container | Docker (multi-stage build, single container) | + +--- + +## Project Structure + +``` +codedump/ +├── client/ # React frontend +│ ├── src/ +│ │ ├── api/index.ts # Typed fetch wrappers (JWT injected automatically) +│ │ ├── hooks/ +│ │ │ ├── useAuth.ts # AuthContext — JWT storage, login/logout +│ │ │ └── useSettings.ts # SettingsContext — branding, accent color +│ │ ├── components/ +│ │ │ ├── layout/ +│ │ │ │ ├── Layout.tsx # App shell (sidebar + outlet) +│ │ │ │ └── Sidebar.tsx # Nav — auth-aware, admin section, logout +│ │ │ ├── projects/ +│ │ │ │ ├── ProjectCard.tsx # Card with progress bar, links, tags +│ │ │ │ └── ProjectForm.tsx # Create/edit form with color picker +│ │ │ ├── tools/ +│ │ │ │ └── ToolCard.tsx # Tool card with NEW badge +│ │ │ └── ui/ +│ │ │ ├── Badge.tsx # Status/role badges +│ │ │ ├── Button.tsx # Primary/secondary/ghost/danger variants +│ │ │ ├── Modal.tsx # Accessible overlay (Escape to close) +│ │ │ └── ProgressBar.tsx # Accent-colored progress indicator +│ │ ├── pages/ +│ │ │ ├── Login.tsx # PIN pad + admin login +│ │ │ ├── Dashboard.tsx # Stats, new tools spotlight, recent projects +│ │ │ ├── Projects.tsx # Filterable project grid +│ │ │ ├── ProjectDetail.tsx # Docs viewer, completion editor, links +│ │ │ ├── Tools.tsx # Tool catalog with search + filter +│ │ │ ├── Settings.tsx # Branding, logo upload, accent color +│ │ │ └── AdminUsers.tsx # User management (admin only) +│ │ └── types/index.ts # Shared TypeScript interfaces +│ ├── index.html +│ ├── vite.config.ts # Dev proxy: /api → localhost:3000 +│ ├── tailwind.config.js +│ └── tsconfig.json +│ +├── server/ # Express backend +│ ├── src/ +│ │ ├── db/schema.ts # SQLite schema, migrations, admin bootstrap +│ │ ├── lib/pinHash.ts # HMAC-SHA256 PIN hashing (deterministic lookup) +│ │ ├── middleware/auth.ts # requireAuth / requireAdmin JWT guards +│ │ └── routes/ +│ │ ├── auth.ts # POST /pin, POST /login, GET /me +│ │ ├── projects.ts # CRUD + tag/category support +│ │ ├── tools.ts # CRUD +│ │ ├── uploads.ts # POST (multer) + DELETE for documents +│ │ ├── settings.ts # GET/PUT settings, POST logo upload +│ │ └── users.ts # Admin-only user CRUD +│ ├── tsconfig.json +│ └── package.json +│ +├── Dockerfile # Multi-stage: client build → server build → runtime +├── docker-compose.yml +├── .dockerignore +├── INSTALL.md # Unraid GUI install guide +└── package.json # npm workspaces root +``` + +--- + +## Database Schema + +**`users`** — Authentication accounts +| Column | Type | Notes | +|---|---|---| +| `id` | TEXT PK | UUID | +| `username` | TEXT UNIQUE | Display name | +| `role` | TEXT | `admin` or `user` | +| `pin_hash` | TEXT UNIQUE | HMAC-SHA256 of 4-digit PIN (users only) | +| `password_hash` | TEXT | bcrypt hash (admins only) | +| `created_at` | TEXT | ISO datetime | + +**`projects`** — Core project records +| Column | Type | Notes | +|---|---|---| +| `id` | TEXT PK | UUID | +| `name` | TEXT | Required | +| `description` | TEXT | | +| `category` | TEXT | e.g. AI/ML, DevOps, Research | +| `status` | TEXT | `active`, `complete`, `archived` | +| `completion` | INTEGER | 0–100 | +| `external_url` | TEXT | Internal or external link | +| `drive_url` | TEXT | Google Drive link | +| `tags` | TEXT | JSON array of strings | +| `accent_color` | TEXT | Hex color for card theming | +| `is_new` | INTEGER | Boolean flag | +| `created_at` / `updated_at` | TEXT | ISO datetime | + +**`documents`** — Files attached to projects +| Column | Type | Notes | +|---|---|---| +| `id` | TEXT PK | UUID | +| `project_id` | TEXT FK | Cascades on project delete | +| `filename` | TEXT | UUID-named file on disk | +| `original_name` | TEXT | Display name | +| `mimetype` | TEXT | | +| `created_at` | TEXT | | + +**`tools`** — Available AI/dev tools catalog +| Column | Type | Notes | +|---|---|---| +| `id` | TEXT PK | UUID | +| `name` | TEXT | | +| `description` | TEXT | | +| `category` | TEXT | | +| `external_url` | TEXT | | +| `is_new` | INTEGER | Boolean — shown in dashboard spotlight | +| `added_at` | TEXT | | +| `notes` | TEXT | Usage tips, caveats | + +**`settings`** — Key/value app configuration +| Key | Default | Description | +|---|---|---| +| `app_title` | `CODEDUMP` | Shown in sidebar and login page | +| `company_name` | `Your Company` | Shown under the app title | +| `logo_url` | `null` | Uploaded or external URL | +| `accent_color` | `#6366f1` | CSS variable applied globally | + +--- + +## Auth Model + +Two account types with separate login flows: + +**Users** — Standard team members +- Select no username; just enter their 4-digit PIN directly on the keypad +- PINs are unique system-wide (enforced by DB unique constraint) +- Stored as `HMAC-SHA256(JWT_SECRET, pin)` — deterministic, allowing single-query lookup +- Can: create/edit/delete projects and tools, upload documents, view all content +- Cannot: access Settings or User Management + +**Admins** — Elevated accounts +- Log in with username + password via the "Admin Login" link on the login page +- Passwords stored as bcrypt hashes (cost factor 10) +- Can: everything users can do, plus Settings (branding/theme) and User Management +- A bootstrap admin is created on first startup from `ADMIN_USERNAME` / `ADMIN_PASSWORD` env vars +- The last admin account cannot be deleted + +**JWT** — 12-hour tokens stored in `localStorage`. Expiry is checked client-side on load; the server re-validates on every request. A 401 response from the server clears the token and redirects to `/login`. + +--- + +## Environment Variables + +| Variable | Default | Description | +|---|---|---| +| `PORT` | `3000` | Server listen port | +| `DATA_DIR` | `./data` | SQLite DB + uploads root on disk | +| `MAX_UPLOAD_MB` | `50` | Max file upload size | +| `ADMIN_USERNAME` | `admin` | Bootstrap admin username (first-run only) | +| `ADMIN_PASSWORD` | `codedump2024` | Bootstrap admin password (first-run only) — change this | +| `JWT_SECRET` | *(insecure default)* | Token signing secret — set to a 32+ char random string | + +Generate a strong `JWT_SECRET`: +```bash +openssl rand -hex 32 +``` + +--- + +## Running Locally + +```bash +# Install all workspace dependencies +npm install + +# Start both server (port 3000) and client (port 5173) with hot reload +npm run dev +``` + +Visit `http://localhost:5173`. The Vite dev server proxies `/api/*` to `localhost:3000`. + +Default admin credentials on first run: `admin` / `codedump2024` + +--- + +## Building for Production + +```bash +npm run build +# Client builds to client/dist/ +# Server builds to server/dist/ +# Server serves client/dist/ as static files +npm start +``` + +--- + +## Docker + +```bash +# Build image +docker build -t codedump:latest . + +# Run with docker-compose (recommended) +docker-compose up -d +``` + +Data persists in `./data/` (local) or `/mnt/user/appdata/codedump/` (Unraid). + +See [INSTALL.md](./INSTALL.md) for the full Unraid GUI setup guide including port mapping, volume paths, and all environment variable fields. + +--- + +## File Upload Details + +- Accepted types: `.md`, `.txt`, `.pdf`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg` +- Files are stored in `DATA_DIR/uploads/` with UUID filenames +- Served publicly at `/api/uploads/:filename` via `express.static` (no auth required — needed for `` tags and the markdown doc viewer) +- Upload and delete operations require authentication +- Logo uploads follow the same path; the URL is saved in settings and served the same way + +--- + +## Deployment Notes + +- SQLite with WAL mode — suitable for a single-server internal tool; no separate database service needed +- All persistent state (DB + uploads) lives under `DATA_DIR` — back up that directory +- The bootstrap admin only runs if no admin account exists in the DB; changing env vars after first run does not change existing credentials +- `JWT_SECRET` must stay consistent across restarts — changing it invalidates all active sessions