Node.js Project Architecture

Node.js project architecture standards for AI-assisted development. Enforces file splitting (<400 lines), config externalization, route modularization, and a...

Security Scan

An instruction-only architecture guide whose requirements and actions match its stated purpose, but it prescribes patterns (hot-reload admin endpoints and storing admin credentials in config.json) that can be insecure if implemented or deployed without care.

Purpose & Capability

Name/description (AI-friendly Node.js project architecture, file-splitting, config externalization, admin dashboard) match the SKILL.md and reference files. The skill requests no unrelated binaries, env vars, or installs — everything in the docs is coherent with structuring projects and adding an admin UI.

Instruction Scope

Runtime instructions focus on splitting files, externalizing config, and adding admin endpoints (/api/config, /admin/config). These are within scope, but the docs explicitly instruct reading and overwriting ./config.json, backing it up, and exposing a config API. That pattern can accidentally expose secrets (if strip logic is incomplete) or enable unauthenticated config changes if 'requireAdmin' is not implemented securely. The guidance gives the agent broad discretion to create network-accessible admin endpoints and perform file writes — expected for this purpose but security-sensitive.

Install Mechanism

No install spec and no code files executed by the platform — instruction-only. This minimizes immediate filesystem or network risk from the skill package itself.

Credentials

The skill declares no required environment variables or credentials (consistent). However, it recommends storing admin credentials and third-party API keys in config.json (examples show admin.password and thirdParty keys). Storing secrets in a writable JSON served by the app increases the risk of accidental exposure; using environment variables or dedicated secret storage is safer for production.

Persistence & Privilege

Skill metadata does not request always:true or elevated privileges and is user-invocable only. The README claim that the skill "auto-activates" on certain prompts is a behavioral description, not a metadata privilege — metadata indicates normal, non-forced inclusion.

Assessment

This is a coherent, instruction-only architecture guide — it won't itself install code or ask for credentials. However, follow-up considerations before adopting its patterns: - Review any produced admin endpoint code carefully. Ensure requireAdmin is implemented with robust authentication (not a plain header in production), use TLS, enforce rate limits, CSRF protection, and logging. - Avoid storing sensitive secrets (admin passwords, API secrets) in a web-served config.json; prefer environment variables or a secrets manager for production. If you must use config files, ensure /api/config never returns secret fields and that backup files are protected. - Validate and sanitize incoming admin POST data before writing config.json, and consider access controls (IP allowlist, OAuth, or token-based auth) rather than a simple header password. - Treat hot-reload in production cautiously: it simplifies operations but can enable misconfiguration or privilege escalation if exposed publicly. - Because the skill is instruction-only, the security risk comes from code you or an agent generate from these instructions — audit generated server/admin code before deploying publicly.

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
Data Tool	Crawler, scraper, scheduler, data sync, analytics	references/tool.md
Content/Utility	Generator, library, publisher, file processing	references/tool.md
Dashboard/Monitor	Charts, real-time, alerts, metrics	references/tool.md
API Service	REST endpoints, middleware, microservice	references/tool.md
SDK/Library	Shared module, build step, multi-consumer	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)

// 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