256 lines
9.6 KiB
Markdown
256 lines
9.6 KiB
Markdown
# 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 `<img>` 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
|