# CodeHub — System Guide & Architecture

> **ฉบับเต็ม** — อธิบายทุกอย่างที่ AI ใหม่ต้องรู้ + ทำไมมีบางอย่างในระบบ

---

## 🎯 1. CodeHub คืออะไร

**CodeHub** = แพลตฟอร์ม **"versioned code repository + AI-readable instructions"** ที่
**https://codehub.sj88ai.com**

- เก็บทุก project พร้อม screenshots, AI prompts/responses, source code
- 31 projects / 65+ versions / 200+ files / 90K+ lines
- FastAPI backend (26 endpoints) + MCP server (13 tools) + nginx
- Kawaii pink theme (sj88ai.com-inspired) ใช้ CSS เดียวกันทั้งเว็บ
- ไม่มี password gate บนหน้าหลัก (admin token แยก)

---

## 📁 2. โครงสร้างไฟล์ — ต้องเข้าใจ

### บน VPS `5.231.28.248`

```
/opt/codeship/ship.py        ← SHIP SCRIPT (canonical) — symlink ไป /workspace/ship.py
/workspace/ship.py           ← symlink → /opt/codeship/ship.py (AI รัน path นี้)

/mnt/16tb/codehub/           ← 16TB XFS storage
├── api/                      FastAPI (systemd: codehub-api)
│   ├── app.py                26 endpoints
│   ├── db.py, models.py     SQLAlchemy
│   └── mcp.py                13 MCP tools
├── builder/generate.py      Static site generator (idempotent)
├── templates/*.py           Python f-string → HTML
├── projects/<slug>/         SOURCE OF TRUTH (filesystem)
│   ├── project.json          icon/category/desc/tags
│   └── versions/vX.Y/
│       ├── meta.json         required: {version, date, user_cmd, ai_response, what_changed, ...}
│       ├── code/             raw source files
│       └── screenshots/      PNG/JPG
├── apps/<slug>/             DEPLOYED APP FILES (served by nginx directly)
├── www/                     GENERATED static output
├── www-static/              Hand-written pages (preserved during rebuild)
└── .cache/                  SQLite + FTS5
```

### Key file paths

| Path | Purpose | AI Action |
|---|---|---|
| `/workspace/ship.py` | Ship script | `python3 /workspace/ship.py ...` |
| `/opt/codeship/ship.py` | Real script (symlinked) | Don't modify directly |
| `/mnt/16tb/codehub/` | CodeHub root | All CodeHub data |
| `/mnt/16tb/codehub/projects/<slug>/` | Project source of truth | Read/write meta.json here |
| `/mnt/16tb/codehub/apps/<slug>/` | Deployed app files | Drop index.html here |
| `/mnt/16tb/codehub/www/` | Generated output | **DO NOT EDIT MANUALLY** (regenerated by builder) |
| `/etc/nginx/sites-available/codehub.sj88ai.com.conf` | nginx config | Source of truth |
| `/etc/nginx/sites-enabled/codehub.sj88ai.com.conf` | nginx active | Symlink of above (or edited copy) |

---

## 🎨 3. The ONE THEME RULE

**ALL pages use ONE CSS file: `/assets/base.css`** (670 lines, 28KB)

- Has CSS variables in `:root` — change variable → all pages update
- Components: nav, hero, buttons, cards, pills, tables, code blocks, lock screen, alerts, callouts
- Fonts: Plus Jakarta Sans (body) + JetBrains Mono (code)
- Colors: kawaii pink (`--accent: #ec4899`)

**To style a new page**: add `<link rel="stylesheet" href="/assets/base.css">`
and use the classes (`.btn`, `.card`, `.pill`, etc.). DO NOT write inline `<style>`.

---

## ⛔ 4. HARD RULES (ไม่ทำตาม = โกรธ)

1. **Live URLs ต้องชี้ `https://codehub.sj88ai.com/<slug>/` เท่านั้น** — ห้าม external VPS
2. **ใช้ base.css** — ไม่เขียน inline `<style>` ในหน้าใหม่
3. **ship.py รันจาก `/workspace/ship.py` เท่านั้น** — ห้าม copy ไปที่อื่น
4. **Templates ใช้ Python f-string** — escape `{` เป็น `{{`
5. **nginx config: แก้ที่ `sites-available` แล้ว symlink หรือ copy ไป `sites-enabled`**
6. **builder/generate.py wipes `www/` แต่ preserve**: `assets/`, `install/`, `ai-guide/`, `handbook/`, `showcase/`, `learn/`, `codehub-briefing/`, `ship-prompt/`

---

## 🚢 5. How to ship a new app (the ONLY way)

### Input: user has a local HTML file
```bash
python3 /workspace/ship.py \
  --name <slug> \
  --file /path/to/index.html \
  --title "Display Title" \
  --description "..." \
  --category "Games" \
  --icon "🎮" \
  --color "#ec4899" \
  --user-cmd "what user asked" \
  --ai-response "what you did" \
  --changes "Line 1\nLine 2" \
  --version 1.0
```

### Input: user wants a starter app (no file)
```bash
python3 /workspace/ship.py \
  --name <slug> \
  --from-template starter \
  --title "..." \
  ...
```

### ⚠️ CRITICAL: ship.py ERROR if `--file` doesn't exist

The current `ship.py` **validates** that `--file` exists before proceeding.
If user said "deploy this file" but didn't provide it → **STOP and ASK**:
- "Where is the file? Please provide absolute path or local file content."

**NEVER invent / make up a file. NEVER create a Trello-lookalike from imagination.**

---

## 🗺 6. URL structure (nginx + CodeHub layout)

| URL pattern | Source | What it is |
|---|---|---|
| `/` | builder → `www/index.html` | Homepage |
| `/handbook/`, `/ai-guide/`, `/install/`, `/ship-prompt/`, `/learn/` | `www-static/` preserved by builder | Gated/educational pages |
| `/stats/`, `/roadmap/`, `/search/`, `/diff/`, `/ai-instructions/` | builder | Built from templates |
| `/project/<slug>/` | builder | Project journey page |
| `/project/<slug>/timeline/` | builder | Timeline + screenshots |
| `/<slug>/` (top-level) | nginx alias to `apps/<slug>/` | **Deployed app** (user-facing) |
| `/demos/` | nginx alias to `apps/demos/` | Demo toys |
| `/codehub-briefing/` | nginx alias to `apps/codehub-briefing/` | AI briefing page |
| `/api/*` | nginx proxy → FastAPI on 127.0.0.1:8765 | API endpoints |
| `/assets/base.css` | builder copies from somewhere | **THE THEME** |

---

## 🔐 7. Auth + secrets

| Secret | Location |
|---|---|
| Admin token | `/etc/codehub-admin-token` (KEY=VALUE, chmod 600) |
| Admin token value | `codehub-admin-9355e4687fd360c70e39191dfab515f4` |
| VPS root password | (in user messages only, never commit) |

Send as `X-Admin-Token: codehub-admin-...` header OR `?password=...` query.

---

## 📦 8. The flowboard DISASTER — what NOT to do

**On 2026-07-08 around 20:32**, an AI was given the ship-prompt content and told:
"deploy this program to the system"

But the user did NOT provide an actual file to ship. The AI then:
- ❌ Created a 110KB "Trello-style kanban" from imagination
- ❌ Used Inter font + dark navy theme (broke kawaii pink)
- ❌ Created 7 dirs, multiple files, fake "project"
- ❌ Added nginx location, project.json, fake version
- ❌ Made it look like a "real" CodeHub project

**Why it happened**: ship.py wasn't on the server, so the AI couldn't run it. ship-prompt page said "run python3 /workspace/ship.py" but the file didn't exist. AI improvised instead of stopping.

**What I fixed**:
1. ✅ Uploaded ship.py to `/opt/codeship/ship.py` + symlink at `/workspace/ship.py`
2. ✅ Installed `paramiko` on server (was missing)
3. ✅ Deleted `/apps/flowboard/`, `/projects/flowboard/`, `/www/project/flowboard/`
4. ✅ Removed nginx `flowboard` location
5. ✅ Restored clean nginx from `sites-available`
6. ✅ Re-added `/ship-prompt/` nginx location + re-uploaded page
7. ✅ Verified `/workspace/ship.py --help` works
8. ✅ End-to-end test: shipped `ship-test-final` app successfully (13s)

**Lesson for future AI**:
- If you can't run ship.py → **STOP and ask user** for the file
- If ship.py says file doesn't exist → **ERROR OUT, do not invent**
- If user says "deploy this" with no file → **ASK "where is the file?"**

---

## 🛠 9. Common operations

### Add a new nginx location (manual)
```bash
# Add to /etc/nginx/sites-enabled/codehub.sj88ai.com.conf in HTTPS server block:
location ^~ /<slug>/ {
    alias /mnt/16tb/codehub/apps/<slug>/;
    index index.html;
    try_files $uri $uri.html $uri/ $uri/index.html =404;
}
location = /<slug> { return 301 https://$host/<slug>/; }

nginx -t && nginx -s reload
```

### Add a new project manually
```bash
mkdir -p /mnt/16tb/codehub/projects/<slug>/versions/v1.0/{code,screenshots}
# Create project.json + meta.json
# (or use POST /api/admin/upload from script)
cd /mnt/16tb/codehub && python3 builder/generate.py
curl -X POST -H "X-Admin-Token: ..." https://codehub.sj88ai.com/api/cache/refresh
```

### Restart FastAPI
```bash
ssh root@5.231.28.248 "rm -rf /mnt/16tb/codehub/api/__pycache__ && systemctl restart codehub-api"
```

### Check nginx config
```bash
ssh root@5.231.28.248 "nginx -t"
ssh root@5.231.28.248 "tail -30 /var/log/nginx/error.log"
```

---

## 🔌 10. API Quick Reference (26 endpoints)

Read-only: `/api/health`, `/api/stats`, `/api/projects`, `/api/categories`, `/api/tags`,
`/api/search?q=`, `/api/project/<slug>`, `/api/project/<slug>/<ver>`,
`/api/project/<slug>/<ver>/code`, `/api/project/<slug>/<ver>/code/<path>`,
`/api/project/<slug>/timeline`, `/api/project/<slug>/<ver>/screenshot/<file>`,
`/api/diff/<slug>/<from>/<to>`, `/api/stats/timeline`, `/api/recent-activity`,
`/api/ai-instructions`, `/api/ai-instructions/<slug>`, `/api/mcp` (POST), `/api/mcp/info`

Admin: `POST /api/admin/upload` (THE upload), `/api/admin/rebuild`, `/api/cache/refresh`,
`/api/search/rebuild`, `/api/admin/backups/*`, `/api/login`, `/api/me`, `/api/logout`

### API quirks
- `version` field: send `"1.0"` not `"v1.0"` (double-v bug)
- `what_changed`: newline-separated, becomes array
- `tags`/`tech_stack`: comma-separated, becomes array
- Code files: `code_files_json` (JSON dict) or `code_zip`
- Defaults `icon='📦'`, `color='#4f9eff'` always written (override)

---

## 🧠 11. Key Lessons (10)

1. **Use base.css, not inline `<style>`** — one theme, easy to update
2. **Use `python3 /workspace/ship.py`** — symlinked to `/opt/codeship/ship.py`
3. **Try nginx `try_files $uri $uri.html $uri/ $uri/index.html =404;`** — supports clean URLs
4. **Preserve `www-static/` dirs in builder** — `assets/`, `learn/`, `ai-guide/`, `handbook/`, `install/`, `showcase/`, `codehub-briefing/`, `ship-prompt/`
5. **paramiko needs install on fresh sandbox** — `pip install --break-system-packages paramiko requests`
6. **GitHub PAT in URL only, never commit** — `https://oauth2:<PAT>@github.com/owner/repo.git`
7. **Don't use sed for nginx config** — sed can delete closing braces, prefer Python `str.replace`
8. **Always run `nginx -t && nginx -s reload`** after config change
9. **Templates use Python f-string** — escape `{` as `{{` and `}` as `}}`
10. **If ship.py fails or file missing → STOP. Don't invent.**

---

## 📍 12. Current state (2026-07-08)

> **Phase 17 — ship.py (one-command ship)** ✅ DONE
> File: `/workspace/ship.py` (21KB) + server copy at `/opt/codeship/ship.py` (symlinked at `/workspace/`)
> Server: `5.231.28.248:22` (root) · Storage: `/mnt/16tb/codehub/apps/<slug>/` · Public: `https://codehub.sj88ai.com/<slug>/`
> Doc: `/codehub-guide/phase-17.md`

| Page | Status | Notes |
|---|---|---|
| `/` | ✅ 200 | kawaii pink, nav complete |
| `/ship-prompt/` | ✅ 200 | pink + copy button + Target Server table + ship.py location |
| `/codehub-guide/` | ✅ 200 | full system doc (markdown) |
| `/codehub-guide/phase-17.md` | ✅ 200 | Phase 17 ship.py spec |
| `/handbook/` | ✅ 200 | pink + nav |
| `/ai-guide/?code=88888888` | ✅ 200 | lock screen + nav |
| `/install/?code=88888888` | ✅ 200 | lock screen + nav |
| `/codehub-briefing/?code=88888888` | ✅ 200 | pink + nav + HARD RULE |
| `/ship-prompt/` | ✅ 200 | pink + copy button |
| `/learn/` + 6 lessons | ✅ 200 | pink + nav + steps |
| `/stats/` | ✅ 200 | pink + SVG chart pink |
| `/roadmap/` | ✅ 200 | pink |
| `/search/?q=` | ✅ 200 | pink + nav |
| `/demos/` | ✅ 200 | pink + 4 toys |
| `/showcase/` | ✅ 200 | pink + 20 apps |
| `/project/<slug>/` (×28) | ✅ 200 | pink + project color title |
| `/flowboard/` | ❌ 404 | REMOVED — was AI mistake |
| `/project/flowboard/` | ❌ 404 | REMOVED |

**Stats**: 30 projects / 65 versions / 90K+ lines / 12 categories

**Secrets in use**:
- VPS: `xMMomKjP917zE5btfimE` (root@5.231.28.248)
- Admin: `codehub-admin-9355e4687fd360c70e39191dfab515f4`
- ship.py: `/opt/codeship/ship.py` (symlink at `/workspace/ship.py`)

---

> 📝 เอกสารนี้เขียนเมื่อ 2026-07-08 หลังจากลบ flowboard disaster
> ถ้าเจอปัญหาใหม่ → เพิ่มหัวข้อ และ update ตรงนี้

---

## 🚢 PHASE 17 — ship.py quick-spec

| Field | Value |
|---|---|
| **Script** | `/workspace/ship.py` (21KB) |
| **Server copy** | `/opt/codeship/ship.py` (symlinked at `/workspace/`) |
| **Target server** | `5.231.28.248:22` (root) |
| **Storage** | `/mnt/16tb/codehub/apps/<slug>/index.html` |
| **Live URL** | `https://codehub.sj88ai.com/<slug>/` |
| **Password** | env `$DEPLOY_VPS_PASS` (NOT in files/IM) |
| **Templates** | `starter`, `counter`, `todo`, `dice` |
| **Time** | 5–15 seconds |
| **Doc** | https://codehub.sj88ai.com/codehub-guide/phase-17.md |

### Usage (2 patterns)

```bash
# A. Ship local file
python3 /workspace/ship.py --name <slug> --file /path/to/index.html \
  --title "..." --description "..." --category "..." \
  --icon "🎮" --color "#ec4899" \
  --user-cmd "..." --ai-response "..." --changes "..." --version 1.0

# B. Generate from template (no file needed)
python3 /workspace/ship.py --name <slug> --from-template starter \
  --title "..." --icon "🚀" --version 1.0
```

### Get help

```bash
python3 /workspace/ship.py --help   # shows all flags + target server + examples
```