REST API Project Structure

Folder StructureBeginner

A well-organized API project structure helps Claude Code navigate your codebase efficiently and apply changes in the right places. This pattern separates routes, controllers, services, and data access layers so that Claude understands where business logic lives versus where HTTP handling happens. Following this structure also makes your CLAUDE.md instructions more precise — you can say 'add a new service' and Claude knows exactly where to create the file.

apirestnode.jsexpressbackendfolder-structure

Pattern Code

my-api/
├── src/
│   ├── routes/              # HTTP route definitions
│   │   ├── users.ts         # /api/users endpoints
│   │   ├── products.ts      # /api/products endpoints
│   │   └── index.ts         # Route aggregator
│   ├── controllers/         # Request/response handling
│   │   ├── userController.ts
│   │   └── productController.ts
│   ├── services/            # Business logic (no HTTP awareness)
│   │   ├── userService.ts
│   │   └── productService.ts
│   ├── repositories/        # Database queries (Prisma/Drizzle)
│   │   ├── userRepo.ts
│   │   └── productRepo.ts
│   ├── middleware/           # Auth, validation, error handling
│   │   ├── auth.ts
│   │   ├── validate.ts
│   │   └── errorHandler.ts
│   ├── utils/               # Shared helpers
│   │   ├── logger.ts
│   │   └── constants.ts
│   ├── types/               # TypeScript type definitions
│   │   └── index.ts
│   └── app.ts               # Express/Fastify app setup
├── tests/
│   ├── unit/                # Mirror src/ structure
│   │   └── services/
│   └── integration/         # API endpoint tests
│       └── users.test.ts
├── prisma/
│   └── schema.prisma        # Database schema
├── CLAUDE.md                # Project rules for Claude Code
├── .env.example
├── package.json
└── tsconfig.json

# CLAUDE.md excerpt for this structure:
# - Routes only handle HTTP (req/res). No business logic.
# - Services contain all business logic. No HTTP awareness.
# - Repositories handle all database queries via Prisma.
# - Tests mirror src/ structure. Co-located unit tests OK.
# - New feature = route + controller + service + repo + test.

Copy this pattern into your project configuration to implement.

Terminal Preview

REST API Project Structure

About REST API Project Structure

Claude Code patterns are proven architectural designs and workflow structures that help you tackle complex development scenarios. REST API Project Structure is a Folder Structure pattern at the Beginner level that provides a tested, repeatable approach you can adapt to your projects for more efficient and consistent results.

Related Patterns

Full-Stack App Structure

Next.js App Router project structure optimized for Claude Code with clear frontend/backend separation.

Monorepo Structure

Turborepo/pnpm workspace monorepo structure with shared packages, apps, and layered CLAUDE.md files.

Documentation Project Structure

Structured folder layout for large documentation projects — reports, proposals, research papers, and knowledge bases.