⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

nodejs-project-arch

abczsl520@abczsl520⭐ 21 stars· last commit 7mo ago· 0 open issues

Node.js project architecture standards for AI-assisted development. Enforces file splitting (<400 lines), config externalization, route modularization, and admin dashboards. Use when creating new Node.js projects, refactoring large single-file codebases, or when AI context window is being consumed by oversized files. Covers H5 games (Canvas/Phaser/Matter.js), data tools (crawlers/scrapers), content platforms, monitoring dashboards, API services, and SDK libraries.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 21 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

nodejs-project-arch

Node.js project architecture standards for AI-assisted development.

An OpenClaw / AI agent skill that enforces modular file structures, keeping every file small enough for AI to read and edit without blowing the context window.

✨ Why?

When AI agents work with large single-file codebases, things go wrong fast:

ScenarioTokens per readContext usage (200K)
3000-line server.js~40K20%
200-line module~2.7K1.3%

Result: Splitting files means 10-15 productive rounds before context compression, vs 3-5 with monolithic files. That's 70-93% token savings per file read.

📐 Core Rules

  • Single file ≤ 400 lines / index.html ≤ 200 lines / server.js entry ≤ 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 init
  • Frontend: HTML skeleton only, JS/CSS in separate files under public/
  • Every project gets admin.html + routes/admin.js for config hot-reload + stats

🎮 Supported Project Types

TypeSignalsReference
H5 GameCanvas, Phaser, Matter.js, game loop, spritesreferences/game.md
Data ToolCrawler, scraper, scheduler, data sync, analyticsreferences/tool.md
Content/UtilityGenerator, library, publisher, file processingreferences/tool.md
Dashboard/MonitorCharts, real-time, alerts, metricsreferences/tool.md
API ServiceREST endpoints, middleware, microservicereferences/tool.md
SDK/LibraryShared module, build step, multi-consumerreferences/sdk.md

📁 Typical Structure

project-name/
  server.js          ← Entry point, only mounts routes (<100 lines)
  config.json        ← All tunable values (admin dashboard can edit)
  db.js              ← Database init + helpers
  routes/
    auth.js          ← Authentication routes
    game.js          ← Core game/business routes
    admin.js         ← Admin API (config CRUD, stats)
  services/          ← Shared business logic
  public/
    index.html       ← Pure HTML skeleton (<200 lines)
    admin.html       ← Admin dashboard
    css/style.css
    js/              ← Split by responsibility, each <400 lines
    assets/

🚀 Installation

For OpenClaw users

Copy the skill to your agents skill directory:

# Clone and copy
git clone https://github.com/abczsl520/nodejs-project-arch.git
cp -r nodejs-project-arch ~/.agents/skills/

# Or if you have clawhub:
# clawhub install nodejs-project-arch

The skill auto-activates when you ask your AI agent to:

  • Create a new Node.js project
  • Refactor a large single-file codebase
  • Split oversized files

For manual reference

Browse the reference docs directly:

📖 Documentation

Full documentation is available on the Wiki:

🔧 Quick Example: config.json Pattern

// server.js — load and serve config
const config = JSON.parse(fs.readFileSync('./config.json', 'utf8'));

app.get('/api/config', (req, res) => {
  const safe = { ...config };
  delete safe.admin;
  res.json(safe);
});

// Admin hot-reload
app.post('/admin/config', requireAdmin, (req, res) => {
  fs.writeFileSync('./config.json.bak', fs.readFileSync('./config.json'));
  fs.writeFileSync('./config.json', JSON.stringify(req.body, null, 2));
  Object.assign(config, req.body);
  res.json({ ok: true });
});

📊 Real-World Token Savings

ScenarioBeforeAfterSavings
Read game feature code~40K tokens~2.7K tokens93%
One dev round (read→edit→verify)~52K tokens~4K tokens92%
4-round SDK session~196K tokens~69K tokens65%
Large data tool module~84K tokens~8K tokens90%

🧬 Part of the project-arch Family

This skill implements the Node.js-specific patterns from project-arch-core — the language-agnostic architecture principles for AI-assisted development.

SkillLanguageStatus
project-arch-coreUniversal principles✅ Foundation
nodejs-project-arch (this)Node.js / Express✅ Available
react-project-archReact / Vite✅ Available
python-project-archPython🔲 Community welcome
go-project-archGo🔲 Community welcome

License

MIT

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md3.4 KBupstream ↗
    ---
    name: nodejs-project-arch
    description: Node.js project architecture standards for AI-assisted development. Enforces file splitting (<400 lines), config externalization, route modularization, and admin dashboards. Use when creating new Node.js projects, refactoring large single-file codebases, or when AI context window is being consumed by oversized files. Covers H5 games (Canvas/Phaser/Matter.js), data tools (crawlers/scrapers), content platforms, monitoring dashboards, API services, and SDK libraries.
    ---
    
    # 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('/api/config', (req, res) => {
      const safe = { ...config };
      delete safe.admin; // strip secrets
      res.json(safe);
    });
    
    // Admin: hot-reload
    app.post('/admin/config', requireAdmin, (req, res) => {
      fs.writeFileSync('./config.json.bak', fs.readFileSync('./config.json'));
      fs.writeFileSync('./config.json', JSON.stringify(req.body, null, 2));
      Object.assign(config, req.body);
      res.json({ ok: true });
    });
    ```
    
    ## Admin Dashboard Pattern (Universal)
    
    `admin.html` auto-generates form from config structure:
    - Password login (`x-admin-password` header)
    - Visual config editor with save + hot-reload
    - Stats overview (users/data/uptime)
    - Config backup history + restore
    
    ## Why This Matters
    
    Large single files consume massive context tokens when AI reads them:
    - 3000-line file → ~40K tokens per read (20% of 200K window)
    - 200-line module → ~2.7K tokens per read (1.3% of window)
    - **Result: 10-15 productive rounds vs 3-5 before context compression**
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/abczsl520-nodejs-project-arch.md

// REPO STATS

21 stars
0 open issues
Last commit: 7mo ago