Initial Project Analysis

In this lesson we demonstrate how to audit a small Express (Node.js) project for software design, modularity, and architectural issues using Claude Code. The aim is a structured findings report with concrete, code-level remediation you can apply incrementally.

In this lesson we perform an automated software-quality audit using Claude Code. If you’ve participated in enterprise code reviews, you already know reviewers check architecture, design patterns, error handling, and operational practices. Claude Code automates that process at scale and produces actionable remediation tied to code locations. Example interactive session that starts Claude Code in the project folder:

jeremy@MACSTUDIO Express-login-demo % claude

* Welcome to Claude Code!

/help for help, /status for your current setup

cwd: /Users/jeremy/Repos/Claude Code Course/Express-login-demo

> Try "refactor <filepath>"

? for shortcuts

In COMPREHENSIVE_SECURITY_REPORT.md

The lesson uses a curated set of review prompts (instead of typing one-off prompts). The prompt set used for this lesson is available in the repo:

https://github.com/JeremyMorgan/claude-code-reviewing-prompts

A dark‑theme screenshot of a GitHub repository page for "Claude-Code-Reviewing-Prompts" showing a list of markdown files (e.g., authentication-flow-review.md, database-security.md) and an About/sidebar panel on the right.

How the review is scoped (condensed prompt used for the audit):

Analyze the project architecture and identify:

Evaluate:
1. Is there clear separation of concerns?
2. Which architectural pattern is used (MVC, Layered, Microservices)?
3. Are there any God objects or modules doing too much?
4. Is the dependency flow clean (no circular dependencies)?
5. Rate the modularity (1-10) with justification

Provide a textual architecture description showing:
- Layer dependencies
- Data flow
- External service integrations
- Potential bottlenecks

Identify anti-patterns:
- Spaghetti code
- Copy-paste programming
- God classes/modules
- Tight coupling
- Missing abstractions

Provide:
- A structured findings report
- A scale of 1/10 on how important each finding is
- Remediation: precise code-level fix or config change (snippets welcome), plus defense-in-depth guidance

Constraints & style:
- Be concrete and cite exact code locations and identifiers.
- Prefer minimal, drop-in fix snippets over prose.
- Do not invent files or functions that aren’t present; if context is missing, mark as Unable to verify and say what code would prove it.
- Write this into a markdown file and place it in the audits/ folder.

While running, Claude Code inspects the repository: listing directories, reading key files, and searching for code patterns. Example actions (condensed):

● List(~/Repos/Claude Code Course/Express-login-demo)
└ Listed 25 paths

● Read(server.js)
└ Read 19 lines

● Read(package.json)
└ Read 25 lines

● List(routes)
└ Listed 4 paths

● Read(routes/auth.js)
└ Read 98 lines

● Read(config/database.js)
└ Read 19 lines

● Read(schema.sql)
└ Read 22 lines

● Search(pattern: "class|function|async function", output_mode: "content")
└ Found 10827 lines

Claude then wrote a structured audit to audits/SOFTWARE_DESIGN_ARCHITECTURE_ANALYSIS.md. The cleaned and consolidated version of that report follows. Project: Express Login Demo

Executive summary

Overall Architecture Score: 4/10 This Express Login Demo exhibits a minimal MVC-inspired structure but contains significant design and operational shortcomings. Business logic is embedded in route handlers, there’s limited abstraction, and the app lacks centralized error handling and input validation. These problems raise technical debt and make the code harder to test, secure, and scale.

Architecture analysis

1. Architectural pattern assessment

Pattern identified: Minimal MVC-like structure

Model: PostgreSQL integration via config/database.js
View: JSON API responses
Controller: Route handlers in routes/auth.js

Separation of concerns: 3/10

Business logic and data access are mixed into route handlers.
No service or repository layer is present.
DB config is separated (positive).

2. Project structure

express-login-demo/
├─ server.js                # Entry point + middleware setup
├─ routes/auth.js           # Authentication routes (monolithic)
├─ config/database.js       # Database connection
├─ schema.sql               # Database schema
└─ package.json             # Dependencies

Modularity: 3/10 — flat structure with most logic in routes/auth.js. No migrations, no distinct repositories or service abstractions.

3. Data flow (high-level)

HTTP request → routes/auth.js (validation, DB queries, auth logic) → config/database.js → PostgreSQL
Missing: service layer, caching, rate limiting, centralized logging, and centralized error handling

Potential bottlenecks:

Single DB pool without explicit connection limits
Blocking synchronous crypto (if used) can stall the Node event loop
No caching — every request hits the database
No rate limiting — auth endpoints exposed to brute-force attempts

Anti-patterns identified

God object / God module (Severity: 8/10)
- Location: routes/auth.js
- Symptom: One file handles routing, validation, business logic, and DB access.
- Impact: Hard to test and maintain.

Primitive obsession (Severity: 6/10)

Location: routes/auth.js — raw SQL and primitive payload handling.

Example:

// Raw SQL and direct token creation
const userQuery = 'SELECT id, email, name, password FROM users WHERE email = $1';
const token = jwt.sign({ userId: user.id, email: user.email }, process.env.JWT_SECRET);

Remediation: Introduce repositories/models and token services.

Copy-paste programming (Severity: 5/10)
- Location: routes/auth.js
- Symptom: Repeated error response patterns and duplicated logic.
- Remediation: Centralize error responses with middleware.
Tight coupling (Severity: 7/10)
- Location: Route handlers require DB, bcrypt, and jwt directly.
- Symptom: Hard to unit test and mock dependencies.
- Remediation: Use dependency injection via factories.
Missing input validation/sanitization (Severity: 6/10)
- Location: routes/auth.js
- Symptom: No robust validation (consider express-validator).
- Remediation: Add validation middleware.

Detailed findings

High priority issues

Issue	Severity	Location	Impact	Remediation
Monolithic route handler	8/10	`routes/auth.js:17-96`	Maintenance, testing	Extract service & repository layers
No global error handling middleware	7/10	`server.js`	Inconsistent responses, leaking errors	Implement centralized error handler & AppError class
Tight coupling	7/10	Throughout	Hard to test/maintain	Use DI/factory functions
No input sanitization	6/10	`routes/auth.js`	Security risk	Add `express-validator` middleware
No structured logging	6/10	App-wide	Low observability	Implement `pino` or `winston` with correlation IDs

Medium priority issues

Issue	Severity	Location	Impact	Remediation
Primitive obsession	6/10	`routes/auth.js`	Type safety, security	Create domain models and repository functions
Missing configuration management	5/10	`server.js`	Environment issues	Add a config module (12-factor approach)
No health checks	4/10	N/A	Deployment readiness	Add `/health` and readiness endpoints

Low priority issues

Issue	Severity	Location	Impact	Remediation
No API versioning	3/10	Routes	Backwards compatibility	Add `/v1/` route prefixes
No request correlation IDs	3/10	N/A	Tracing/debugging	Add correlation middleware
No graceful shutdown	2/10	`server.js`	Deployment stability	Handle SIGTERM/SIGINT and drain DB connections

Recommended architecture improvements

Layered architecture (conceptual)

+-----------------------------------------+
|             Routes Layer                |
+-----------------------------------------+
|           Controllers Layer             |
+-----------------------------------------+
|             Services Layer              |
+-----------------------------------------+
|       Data Access Layer (Repositories)  |
+-----------------------------------------+
|             Models Layer                |
+-----------------------------------------+

Proposed directory structure

src/
├─ controllers/     # Request handling logic
├─ services/        # Business logic
├─ models/          # Domain models
├─ repositories/    # Data access layer
├─ middleware/      # Cross-cutting concerns
├─ utils/           # Utilities
├─ config/          # Configuration management
└─ constants/       # Application constants

Dependency flow (text diagram)

Client → Routes → Controllers → Services → Repositories → Database
                            ↓
                         Middleware (auth, validation, logging)

Concrete remediations (drop-in examples)

Below are small, focused code patterns to reduce coupling, improve testability, and add defenses.

Auth service (move business logic out of routes):

// src/services/AuthService.js
class AuthService {
  constructor(userRepository, passwordService, tokenService) {
    this.userRepository = userRepository;
    this.passwordService = passwordService;
    this.tokenService = tokenService;
  }

  async authenticate(email, password) {
    const user = await this.userRepository.findByEmail(email);
    if (!user || !(await this.passwordService.verify(password, user.password_hash))) {
      const err = new Error('Invalid credentials');
      err.statusCode = 401;
      throw err;
    }
    const token = await this.tokenService.createToken({ userId: user.id, email: user.email });
    return { user, token };
  }
}

module.exports = AuthService;

Repository abstraction for data access:

// src/repositories/userRepository.js
const pool = require('../../config/database');

async function findByEmail(email) {
  const result = await pool.query(
    'SELECT id, email, name, password_hash FROM users WHERE email = $1',
    [email]
  );
  return result.rows[0] || null;
}

module.exports = { findByEmail };

Use a factory to wire routes with injected services:

// src/routes/createAuthRouter.js
const express = require('express');

function createAuthRouter(authService, validatorMiddleware) {
  const router = express.Router();

  router.post('/login', validatorMiddleware, async (req, res, next) => {
    try {
      const { email, password } = req.body;
      const { user, token } = await authService.authenticate(email, password);
      res.json({ token, user: { id: user.id, email: user.email, name: user.name } });
    } catch (err) {
      next(err);
    }
  });

  return router;
}

module.exports = createAuthRouter;

Input validation middleware using express-validator:

// src/middleware/validators/authValidator.js
const { body, validationResult } = require('express-validator');

const loginValidation = [
  body('email').isEmail().normalizeEmail(),
  body('password').isLength({ min: 8 }).trim(),
  (req, res, next) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(422).json({ errors: errors.array() });
    }
    next();
  }
];

module.exports = { loginValidation };

Centralized error handler:

// src/middleware/errorHandler.js
function errorHandler(err, req, res, next) {
  const status = err.statusCode || 500;
  const message = status < 500 ? err.message : 'Internal server error';
  // Example: logger.error(err);
  res.status(status).json({ error: message });
}

module.exports = errorHandler;

Token service:

// src/services/tokenService.js
const jwt = require('jsonwebtoken');

function createToken(payload) {
  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '1h' });
}

module.exports = { createToken };

Security & operational recommendations

Sanitize and validate all inputs (e.g., express-validator).
Always use parameterized queries (prepared statements) to prevent SQL injection.
Run CPU-bound crypto (bcrypt) using async APIs; consider background workers for heavy tasks.
Protect auth endpoints with rate limiting (express-rate-limit).
Implement structured logging (pino or winston) and attach correlation IDs to requests.
Add health and readiness endpoints for orchestration tooling.
Implement graceful shutdown to drain DB/pool connections on SIGTERM/SIGINT.

Final assessment and next steps

Current state: Functional but with high architectural debt.
Technical debt: High — refactoring required for scale and maintainability.
Immediate actions:
1. Extract services and repositories from route handlers.
2. Add global error handling middleware and an AppError pattern.
3. Add input validation and sanitization.
4. Introduce DI/factory functions to decouple dependencies.
5. Implement structured logging and basic operational endpoints.
Long-term:
1. Migrate to a layered architecture with clear responsibilities.
2. Add automated tests (unit + integration).
3. Add configuration management and environment-driven settings.
4. Integrate observability: metrics & tracing.

This analysis delivers a prioritized set of findings and concrete code examples that you can apply incrementally. Subsequent lessons will expand this with more detailed design principles and a targeted security audit.

Links and references

express-validator: https://express-validator.github.io/docs/
pino (structured logging): https://getpino.io/
winston: https://github.com/winstonjs/winston
express-rate-limit: https://www.npmjs.com/package/express-rate-limit
JSON Web Tokens (JWT): https://jwt.io/
Node.js best practices & architecture: https://nodejs.org/en/docs/ (general guidance)

Introduction

Getting Started with Claude Code

Working with Claude Code

Code Review with Claude Code

Security Auditing with Claude Code

Advanced Features

Initial Project Analysis

Executive summary

Architecture analysis

1. Architectural pattern assessment

2. Project structure

3. Data flow (high-level)

Anti-patterns identified

Detailed findings

High priority issues

Medium priority issues

Low priority issues

Recommended architecture improvements

Layered architecture (conceptual)

Proposed directory structure

Dependency flow (text diagram)

Concrete remediations (drop-in examples)

Security & operational recommendations

Final assessment and next steps

Links and references

Watch Video

​Executive summary

​Architecture analysis

​1. Architectural pattern assessment

​2. Project structure

​3. Data flow (high-level)

​Anti-patterns identified

​Detailed findings

​High priority issues

​Medium priority issues

​Low priority issues

​Recommended architecture improvements

​Layered architecture (conceptual)

​Proposed directory structure

​Dependency flow (text diagram)

​Concrete remediations (drop-in examples)

​Security & operational recommendations

​Final assessment and next steps

​Links and references

Watch Video

Executive summary

Architecture analysis

1. Architectural pattern assessment

2. Project structure

3. Data flow (high-level)

Anti-patterns identified

Detailed findings

High priority issues

Medium priority issues

Low priority issues

Recommended architecture improvements

Layered architecture (conceptual)

Proposed directory structure

Dependency flow (text diagram)

Concrete remediations (drop-in examples)

Security & operational recommendations

Final assessment and next steps

Links and references