nodejs-project-arch

# Node.js Project Architecture for AI-Friendly Development

Architecture standards that keep files small enough for AI agents to read/edit without blowing the context window.

## Core Rules

- Single file max **400 lines**, `index.html` max **200 lines**, `server.js` entry max **100 lines**
- All tunable values in `config.json`, loaded at runtime, editable via admin dashboard
- Backend: `routes/` by domain, `services/` for shared logic, `db.js` for database
- Frontend: HTML skeleton only, JS/CSS in separate files
- Every project gets `admin.html` + `routes/admin.js` for config hot-reload

## Project Type Selection

Determine project type, then read the corresponding reference:

| Type | Signals | Reference |
|------|---------|-----------|
| **H5 Game** | Canvas, Phaser, Matter.js, game loop, sprites | [references/game.md](references/game.md) |
| **Data Tool** | Crawler, scraper, scheduler, data sync, analytics | [references/tool.md](references/tool.md) |
| **Content/Utility** | Generator, library, publisher, file processing | [references/tool.md](references/tool.md) |
| **Dashboard/Monitor** | Charts, real-time, alerts, metrics | [references/tool.md](references/tool.md) |
| **API Service** | REST endpoints, middleware, microservice | [references/tool.md](references/tool.md) |
| **SDK/Library** | Shared module, build step, multi-consumer | [references/sdk.md](references/sdk.md) |

## Quick Start (All Types)

1. Identify project type from table above
2. Read the corresponding reference file
3. Create directory structure per the reference
4. Extract hardcoded values → `config.json`
5. Split large files by function (each <400 lines)
6. Add `routes/admin.js` + `admin.html`
7. Frontend: `config.js` fetches `/api/config` at startup, code reads `GAME_CONFIG.xxx` or `APP_CONFIG.xxx`
8. Test locally → backup → deploy

## config.json Pattern (Universal)

```javascript
// Server: load and serve config
const config = JSON.parse(fs.readFileSync('./config.json', 'utf8'));
app.get(...

<div align="center">

# 🏗️ nodejs-project-arch

**AI-friendly Node.js project architecture standards**

*Keep every file under 400 lines. Save 70-93% tokens. Get 3x more productive AI rounds.*

[![ClawHub](https://img.shields.io/badge/ClawHub-nodejs--project--arch-blue?style=flat-square)](https://clawhub.com/skills/nodejs-project-arch)
[![GitHub stars](https://img.shields.io/github/stars/abczsl520/nodejs-project-arch?style=flat-square)](https://github.com/abczsl520/nodejs-project-arch/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)

[Install](#-installation) · [Game Arch](#-h5-game) · [Tool Arch](#-data-tool--api--dashboard) · [SDK Arch](#-sdklibrary) · [Wiki](https://github.com/abczsl520/nodejs-project-arch/wiki)

</div>

---

## 🤯 The Problem

AI agents working with large codebases hit the context window wall fast:

```
3000-line server.js  →  ~40K tokens per read  →  20% of context gone
After 3-5 rounds     →  context compression   →  agent forgets everything
```

## ✅ The Solution

Split by function. Each file stays small. AI reads only what it needs:

```
200-line module      →  ~2.7K tokens per read  →  1.3% of context
After 10-15 rounds   →  still going strong     →  no compression needed
```

### Real-World Token Savings

| Scenario | Before | After | Savings |
|----------|--------|-------|---------|
| Read one game feature | 40K tokens | 2.7K tokens | **93%** |
| Full dev round (read→edit→verify) | 52K tokens | 4K tokens | **92%** |
| 4-round SDK session | 196K tokens | 69K tokens | **65%** |
| Large data tool module | 84K tokens | 8K tokens | **90%** |

## 📐 Core Rules

```
✅ Single file        ≤ 400 lines
✅ index.html         ≤ 200 lines
✅ server.js (entry)  ≤ 100 lines
✅ Tunable values     → config.json (hot-reloadable)
✅ Backend            → routes/ by domain + services/ for shared logic
✅ Frontend           → HTML skeleton + separate JS/CSS files
✅ Every project      → admin.html + rout...