9.6 KiB
9.6 KiB
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_PASSWORDenv 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:
openssl rand -hex 32
Running Locally
# 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
npm run build
# Client builds to client/dist/
# Server builds to server/dist/
# Server serves client/dist/ as static files
npm start
Docker
# 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 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/:filenameviaexpress.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_SECRETmust stay consistent across restarts — changing it invalidates all active sessions