---
name: Fix Template Structure
overview: Restructure services/_template to align with microservices platform architecture by removing duplicate Docker/Traefik configs and refactoring ARCHITECTURE.md to focus on single service context with platform integration.
todos:
  - id: delete-docker-compose
    content: Delete docker-compose.yml and docker-compose.prod.yml from services/_template/
    status: completed
  - id: delete-traefik-config
    content: Delete services/_template/traefik/ directory
    status: completed
  - id: refactor-architecture-md
    content: "Refactor ARCHITECTURE.md with clear sections: Single Service Architecture, Platform Integration, Deployment Context"
    status: completed
  - id: update-readme-deployment
    content: Update README.md to remove Docker Development option and add Platform Integration section
    status: completed
  - id: update-readme-traefik
    content: Update README.md Traefik references to point to infra/traefik/ and explain Docker labels
    status: completed
---

# Fix Template Structure for Microservices Platform

## Problem Summary

The `services/_template` currently contains configurations that conflict with the platform-level setup:

1. Docker Compose files that duplicate `deployments/local/docker-compose.yml` functionality
2. Traefik configuration that duplicates `infra/traefik/` global config
3. ARCHITECTURE.md that describes multi-service architecture instead of single service template

## Proposed Changes

### 1. Remove Docker Compose Files

**Files to delete:**

- [`services/_template/docker-compose.yml`](services/_template/docker-compose.yml) - Full environment setup (conflicts with deployments/local/)
- [`services/_template/docker-compose.prod.yml`](services/_template/docker-compose.prod.yml) - Production overrides (should be in deployments/)

**File to keep:**

- [`services/_template/docker-compose.test.yml`](services/_template/docker-compose.test.yml) - Isolated test environment (useful for CI/CD)

**Rationale:**

- Template services should be deployed via `deployments/local/docker-compose.yml`
- Individual services don't need their own compose files for orchestration
- Test compose file is legitimate for isolated testing

### 2. Remove Duplicate Traefik Configuration

**Directory to delete:**

- `services/_template/traefik/` - Contains duplicate traefik.yml and dynamic.yml

**Rationale:**

- Traefik is a platform-level API Gateway managed at `infra/traefik/`
- Service discovery happens via Docker labels in `deployments/local/docker-compose.yml`
- Services don't configure Traefik directly; they register via labels

**Example of correct pattern:**

```yaml
# In deployments/local/docker-compose.yml
services:
  my-service:
    labels:
                                                                                                                                                                                                                                                   - "traefik.enable=true"
                                                                                                                                                                                                                                                   - "traefik.http.routers.my-service.rule=PathPrefix(`/api/v1/my-service`)"
                                                                                                                                                                                                                                                   - "traefik.http.services.my-service.loadbalancer.server.port=5000"
```

### 3. Refactor ARCHITECTURE.md

**Current issues:**

- Shows multi-service architecture (Auth, User, Product, Order, Payment)
- Mixes single service internals with platform-level concerns
- Unclear context about what the template represents

**New structure:**

```markdown
# Service Template Architecture

## Part 1: Single Service Architecture (Internal)
- Component layers: Controller → Service → Repository
- Middleware chain: Correlation → Auth → Validation → Error → Logger → Metrics
- Data flow within one service
- Internal dependencies: Database, Redis, Jaeger client

## Part 2: Platform Integration (External)
- How this service fits in the microservices platform
- Integration with Traefik API Gateway (via Docker labels)
- Shared infrastructure: Redis, PostgreSQL, Observability stack
- Service discovery and registration
- Inter-service communication patterns

## Part 3: Deployment Context
- Reference to deployments/local/docker-compose.yml
- How to add this service to the platform
- Environment variables and configuration
```

**Diagrams to update:**

1. **Internal Service Architecture** - Focus on single service layers
```mermaid
graph TD
    Request[HTTP Request] --> Traefik[Traefik Gateway]
    Traefik -->|Routes to Service| Middleware[Middleware Chain]
    
    subgraph SingleService[Single Service Boundary]
        Middleware --> Correlation[Correlation ID]
        Correlation --> Auth[Authentication]
        Auth --> Validation[Validation]
        Validation --> Router[Router]
        Router --> Controller[Controller]
        Controller --> Service[Service Layer]
        Service --> Repository[Repository]
        Repository --> Database[(PostgreSQL)]
        Service --> Cache[(Redis)]
    end
    
    Service -.->|Metrics| Prometheus[Prometheus]
    Service -.->|Traces| Jaeger[Jaeger]
```

2. **Platform Integration** - Show how service fits in ecosystem
```mermaid
graph TD
    Client[Client] --> Traefik[Traefik API Gateway]
    
    subgraph Platform[Microservices Platform]
        Traefik --> AuthService[Auth Service]
        Traefik --> YourService[Your Service from Template]
        Traefik --> OtherService[Other Services]
        
        YourService --> SharedDB[(Shared PostgreSQL)]
        YourService --> SharedRedis[(Shared Redis)]
        
        AuthService -.->|JWT Validation| YourService
    end
    
    subgraph Observability[Observability Stack]
        Prometheus[Prometheus]
        Grafana[Grafana]
        Jaeger[Jaeger]
        Loki[Loki]
    end
    
    YourService -.->|Metrics| Prometheus
    YourService -.->|Traces| Jaeger
    YourService -.->|Logs| Loki
```


### 4. Update README.md References

**Changes needed in [`services/_template/README.md`](services/_template/README.md):**

1. Remove "Option 2: Docker Development" section (lines 73-91)

                                                                                                                                                                                                                                                                                                                                                                                                - This references the deleted docker-compose.yml
                                                                                                                                                                                                                                                                                                                                                                                                - Replace with reference to platform deployment

2. Update "Getting Started" section:

                                                                                                                                                                                                                                                                                                                                                                                                - Point to `deployments/local/docker-compose.yml` for full platform
                                                                                                                                                                                                                                                                                                                                                                                                - Explain how to add this service to the platform
                                                                                                                                                                                                                                                                                                                                                                                                - Keep local development instructions (without docker-compose)

3. Remove "Docker Compose Files" section (lines 472-476)

                                                                                                                                                                                                                                                                                                                                                                                                - Only docker-compose.test.yml remains

4. Update "Traefik API Gateway" section (lines 494+)

                                                                                                                                                                                                                                                                                                                                                                                                - Remove references to local traefik/ directory
                                                                                                                                                                                                                                                                                                                                                                                                - Point to `infra/traefik/` for configuration
                                                                                                                                                                                                                                                                                                                                                                                                - Explain Docker labels for service registration

**New section to add:**

````markdown
## Adding This Service to the Platform

### 1. Add to deployments/local/docker-compose.yml

```yaml
services:
  your-service:
    build:
      context: ../..
      dockerfile: services/your-service/Dockerfile
    container_name: your-service-local
    environment:
                                                                                                                                                                                                                                                   - NODE_ENV=development
                                                                                                                                                                                                                                                   - PORT=5002
                                                                                                                                                                                                                                                   - DATABASE_URL=${DATABASE_URL}
                                                                                                                                                                                                                                                   - REDIS_HOST=redis
                                                                                                                                                                                                                                                   - JWT_SECRET=${JWT_SECRET}
    depends_on:
      redis:
        condition: service_healthy
    networks:
                                                                                                                                                                                                                                                   - microservices-network
    labels:
                                                                                                                                                                                                                                                   - "traefik.enable=true"
                                                                                                                                                                                                                                                   - "traefik.http.routers.your-service.rule=PathPrefix(`/api/v1/your-service`)"
                                                                                                                                                                                                                                                   - "traefik.http.services.your-service.loadbalancer.server.port=5002"
````

### 2. Start the Platform

```bash
cd deployments/local
docker-compose up -d
```

### 3. Access Your Service

- API: http://localhost/api/v1/your-service
- Health: http://localhost/api/v1/your-service/health
- Docs: http://localhost/api/v1/your-service/api-docs

```

## Implementation Steps

1. Delete `services/_template/docker-compose.yml`
2. Delete `services/_template/docker-compose.prod.yml`
3. Delete `services/_template/traefik/` directory
4. Refactor `services/_template/ARCHITECTURE.md`:

                                                                                                                                                                                                                                                                                                                                                                                                - Add clear section headers for Single Service vs Platform Integration
                                                                                                                                                                                                                                                                                                                                                                                                - Update diagrams to show correct context
                                                                                                                                                                                                                                                                                                                                                                                                - Add deployment context section

5. Update `services/_template/README.md`:

                                                                                                                                                                                                                                                                                                                                                                                                - Remove Docker Development option
                                                                                                                                                                                                                                                                                                                                                                                                - Remove Docker Compose Files section
                                                                                                                                                                                                                                                                                                                                                                                                - Update Traefik references
                                                                                                                                                                                                                                                                                                                                                                                                - Add "Adding This Service to the Platform" section

6. Keep `services/_template/docker-compose.test.yml` for isolated testing

## Files Affected

- Delete: `services/_template/docker-compose.yml`
- Delete: `services/_template/docker-compose.prod.yml`
- Delete: `services/_template/traefik/traefik.yml`
- Delete: `services/_template/traefik/dynamic.yml`
- Modify: `services/_template/ARCHITECTURE.md`
- Modify: `services/_template/README.md`
- Keep: `services/_template/docker-compose.test.yml`
- Keep: `services/_template/Dockerfile`

## Expected Outcome

After these changes:

1. Template structure clearly represents a single microservice
2. No confusion about deployment - services are added to `deployments/local/docker-compose.yml`
3. Traefik configuration is centralized at `infra/traefik/`
4. ARCHITECTURE.md clearly separates internal service architecture from platform integration
5. Developers understand how to use the template in the microservices platform context