Creating Service Scaffolds

Create standardized directory structure and boilerplate for microservices and feature modules.

What you should do

1. Analyze project structure and language – Examine the repository root for:

   • Language-specific files (package.json, pyproject.toml, go.mod, etc.)
   • Existing service directories or modules to understand naming conventions
   • Configuration files (.eslintrc, pytest.ini, docker-compose.yml)
   • Testing framework and directory structure (tests/, spec/, __tests__/)

2. Determine service name and location – Based on the project structure:

   • Use kebab-case for directory names (e.g., user-service, payment-gateway)
   • Place services in appropriate location (services/, apps/, src/services/)
   • Ensure name doesn't conflict with existing modules

3. Create standard directory structure – Generate the following directories:

   • /src – Main source code
   • /tests/unit – Unit tests
   • /tests/integration – Integration tests
   • /tests/fixtures – Test data and mocks
   • /docs – Service-specific documentation
   • /config – Configuration files (if applicable)

4. Generate core boilerplate files – Create language-appropriate files:

   • Main entry point (index.js, main.py, main.go, etc.)
   • Configuration handler (config.js, settings.py, config.go)
   • Error handling utilities (errors.js, exceptions.py)
   • Basic service interface or API definition

5. Create testing scaffolding – Generate test files:

   • Unit test template with framework imports and basic structure
   • Integration test template with service initialization
   • Mock data files in /tests/fixtures
   • Test configuration file if needed

6. Generate service documentation – Create initial documentation:

   • README.md with service overview, setup instructions, and API reference
   • CHANGELOG.md for tracking service versions
   • API.md or OpenAPI specification (if service exposes APIs)
   • Architecture decision records template in /docs/adr/

7. Create CI/CD configuration – Generate pipeline files:

   • Service-specific build steps (Docker, build scripts)
   • Test execution configuration
   • Deployment configuration templates
   • Quality gates and code coverage requirements

8. Setup dependency management – Initialize dependency files:

   • Language-specific dependency file (package.json, requirements.txt, go.mod)
   • Development dependencies for testing and linting
   • Lock files for reproducible builds

9. Configure linting and formatting – Setup code quality tools:

   • Copy or inherit project-wide linting configuration
   • Service-specific linting rules if needed
   • Pre-commit hooks for code quality enforcement
   • Code formatting configuration

10. Generate service templates – Create reusable code templates:

    • Controller/handler templates with standard patterns
    • Model/entity templates with validation
    • Service layer templates with error handling
    • Database migration templates (if applicable)

11. Initialize version control – Setup service tracking:

    • Add service to main project documentation
    • Update root README.md with service reference
    • Create initial git commit for service structure
    • Tag initial service version

12. Validate and test scaffold – Verify the generated structure:

    • Run dependency installation
    • Execute initial test suite to ensure framework works
    • Validate linting passes on generated code
    • Check that build process completes successfully
    • Generate scaffold report with next steps and recommendations