---

name: data-service description: Use when scaffolding, auditing, or validating MetaSaver data service packages. Covers feature-based structure, service/controller/routes pattern, middleware integration, and API endpoint setup. Requires @metasaver/core-service-utils, {project}-contracts, {project}-database packages. File types: .ts, package.json. allowed-tools: Read, Write, Edit, Bash, Glob

Data Service Package Structure for MetaSaver

Purpose

This skill documents the complete file and folder organization for MetaSaver data service packages (e.g., rugby-crm-service). Data services are Express-based API packages that coordinate between database clients and HTTP handlers using a feature-based structure.

Data services provide:

• Feature-based organization with service/controller/routes per feature
• Service classes handling Prisma database operations
• Controllers coordinating validation and error handling
• Route definitions with JWT auth and permission checking
• Health check and API versioning
• Environment configuration and initialization

Use when:

• Scaffolding a new data service package
• Auditing an existing data service for compliance
• Adding a new feature (service + controller + routes)
• Setting up middleware (auth, logging, error handling)
• Creating health checks and API versioning structure

Directory Structure Reference

Package Root Files

packages/services/{project}-service/
├── package.json              # Package metadata and scripts
├── tsconfig.json             # TypeScript configuration
├── README.md                 # Package documentation
├── .env.example              # Environment variable template
├── eslint.config.js          # ESLint configuration (flat config)
├── Dockerfile                # Docker build configuration
└── dist/                     # Build output (generated)

Source Directory Structure

src/
├── index.ts                  # Service entry point
├── env.ts                    # Environment configuration
├── server.ts                 # Express app factory
├── routes/
│   └── register.ts           # Route registration
├── middleware/
│   ├── auth.ts               # JWT auth middleware
│   ├── error.ts              # Error handling middleware
│   └── logging.ts            # Request logging middleware
└── features/
    └── {feature}/
        ├── index.ts          # Feature barrel export
        ├── {feature}.service.ts      # Service class (Prisma operations)
        └── {feature}.controller.ts   # Controller (validation + response)

Complete Example:

packages/services/rugby-crm-service/
├── package.json
├── tsconfig.json
├── .env.example
├── eslint.config.js
├── README.md
├── Dockerfile
├── src/
│   ├── index.ts
│   ├── env.ts
│   ├── server.ts
│   ├── routes/
│   │   └── register.ts
│   ├── middleware/
│   │   ├── auth.ts
│   │   ├── error.ts
│   │   └── logging.ts
│   └── features/
│       ├── users/
│       │   ├── index.ts
│       │   ├── users.service.ts
│       │   └── users.controller.ts
│       ├── teams/
│       │   ├── index.ts
│       │   ├── teams.service.ts
│       │   └── teams.controller.ts
│       └── index.ts
└── dist/                     # Build output (generated)

Key Packages

Package	Purpose	Key Exports
@metasaver/core-service-utils	Service factory and utilities	createService, ApiError, asyncHandler
{project}-contracts	Zod validation schemas and types	Validation schemas, types
{project}-database	Prisma client and database types	prisma, Prisma types
express	HTTP framework	Express Router, middleware
jsonwebtoken	JWT token creation and verification	sign, verify

File Organization Rules

Package.json Structure

Required Fields:

• name: @metasaver/{project}-service (always scoped)
• version: 0.1.0 (start with patch version)
• type: "module" (ESM packages)
• main: "./dist/index.js"
• types: "./dist/index.d.ts"

Required Scripts:

• build: TypeScript compilation (tsc -b)
• clean: Remove build artifacts
• dev: Run with tsx for development (tsx watch src/index.ts)
• start: Production server startup
• lint, lint:fix, lint:tsc, prettier, prettier:fix
• test:unit: Unit tests (stub or actual)

See templates/package.json.template for complete template.

Environment Configuration

Rule: Export a single env object with all configuration, type-safe with defaults.

Variable Naming: {PROJECT_UPPER}_{SETTING_NAME} (e.g., RUGBY_CRM_SERVICE_PORT)

See templates/env.ts.template for implementation.

TypeScript Configuration

Rule: Extend base config with proper ESM settings.

See templates/tsconfig.json.template for configuration.

Service Class Pattern

Key Points:

• Class-based for organization and testability
• Methods return typed results (Prisma types from contracts)
• Use include for eager-loading relations
• No HTTP concerns (pure data layer)
• Standard methods: getAll, getById, create, update, delete

See templates/feature-service.ts.template for implementation.

Controller Pattern

Key Points:

• asyncHandler wraps async functions to catch errors automatically
• Uses Zod schemas from contracts package for validation
• ApiError.notFound() for consistent error responses
• Returns { data: {...} } for consistent response format
• HTTP status codes follow REST conventions

See templates/feature-controller.ts.template for implementation.

Routes Registration Pattern

Key Points:

• Health check at root level (no authentication)
• All API routes under /api/v1 with versioning
• Auth middleware applied to all API routes
• Feature routers mounted with base paths

See templates/register.ts.template for implementation.

Server Initialization Pattern

Key Points:

• Factory function returns app instance
• Middleware order: JSON → Logging → Routes → Error handling
• Error middleware must be last in stack

See templates/server.ts.template and templates/index.ts.template.

Feature Export Pattern

Rule: Export service and routes via barrel export.

export { {Feature}Service } from "./{feature}.service.js";
export { router as {Feature}Routes } from "./{feature}.controller.js";

See templates/feature-index.ts.template.

Workflow: Scaffolding New Data Service Package

1. Create Package Directory

   mkdir -p packages/services/{project}-service/src/{features,middleware,routes}
   

2. Create Configuration Files (use templates)

   • package.json, tsconfig.json, .env.example, eslint.config.js, Dockerfile

3. Create Core Service Files (use templates)

   • src/env.ts, src/server.ts, src/index.ts

4. Create Middleware Files (use templates)

   • src/middleware/auth.ts, src/middleware/error.ts, src/middleware/logging.ts

5. Create Route Registration (use template)

   • src/routes/register.ts

6. Create Features (repeat per feature)

   • src/features/{feature}/index.ts
   • src/features/{feature}/{feature}.service.ts
   • src/features/{feature}/{feature}.controller.ts

7. Create Feature Index (aggregates all features)

   • src/features/index.ts

8. Test Build and Run

   pnpm --filter @metasaver/{project}-service build
   pnpm --filter @metasaver/{project}-service dev
   

Workflow: Adding New Feature

1. Create feature directory: mkdir -p src/features/{feature}
2. Create service class (from template)
3. Create controller (from template)
4. Create feature barrel export (from template)
5. Register in src/routes/register.ts
6. Update src/features/index.ts
7. Build and test

Audit Checklist

Package Structure

• Package directory at packages/services/{project}-service/
• All required subdirectories: src/features, src/middleware, src/routes
• Build output in dist/ (git-ignored)

package.json

• Name: @metasaver/{project}-service (scoped)
• Version: 0.1.0 (semantic versioning)
• Type: "module" (ESM)
• All required scripts: build, clean, dev, start, lint, prettier, test
• Correct dependencies: express, jsonwebtoken, @metasaver/core-service-utils
• Workspace dependencies: {project}-contracts, {project}-database

TypeScript Configuration

• tsconfig.json extends @metasaver/core-typescript-config/base
• Proper module settings for ESM (module: "ESNext")
• Correct rootDir: "./src" and outDir: "./dist"

Environment Configuration

• src/env.ts exports single env object
• .env.example exists (committed)
• No hardcoded secrets in code

Server Initialization

• src/server.ts exports createServer() function
• src/index.ts creates server and listens on env.PORT
• Graceful shutdown implemented

Middleware

• src/middleware/auth.ts exists (JWT verification)
• src/middleware/error.ts exists (error response formatting)
• src/middleware/logging.ts exists (request logging)
• Error middleware captures async errors via asyncHandler

Routes & Features

• src/routes/register.ts centralizes all route mounting
• /health check available without authentication
• /api/v1 versioning prefix
• All API routes require authentication
• Each feature has: service, controller in own folder
• Feature index.ts exports service and routes
• Controllers use asyncHandler wrapper
• Controllers use Zod validation from contracts

Service Classes

• Methods return properly typed results
• No HTTP concerns (pure data operations)
• Standard methods: getAll, getById, create, update, delete

Controllers

• All async operations wrapped with asyncHandler
• Consistent response format: { data: {...} }
• Proper HTTP status codes (200, 201, 204, 404)

Build & Compilation

• pnpm build succeeds without errors
• dist/ folder contains compiled files
• No type errors in pnpm lint:tsc

Common Violations & Fixes

Violation: Express handlers not wrapped with asyncHandler

// WRONG
router.get("/:id", async (req, res) => { ... });

// RIGHT
router.get("/:id", asyncHandler(async (req, res) => { ... }));

Violation: Service class with HTTP concerns

// WRONG - service knows about HTTP
async getUser(req: Request): Promise<Response> { ... }

// RIGHT - service is pure data layer
async getById(id: string): Promise<User | null> { ... }

Violation: Custom validation instead of Zod

// WRONG
if (!req.body.name || typeof req.body.name !== "string") { ... }

// RIGHT
const validated = CreateUserSchema.parse(req.body);

Violation: Direct environment variable access throughout code

// WRONG - scattered env access
const port = process.env.PORT;

// RIGHT - centralized env object
import { env } from "./env.js";

Related Skills

• prisma-database - Prisma schema and database client setup
• contracts-package - Zod validation schemas and type definitions
• typescript-configuration - TypeScript configuration (tsconfig.json)
• eslint-agent - ESLint configuration (eslint.config.js)
• monorepo-structure - Monorepo organization (packages/services/*)