Service Repository Migration Plan#

This document outlines the plan to separate the ./service directory into a standalone service git repository.

Architecture After Migration#

tinsnip/                    # Infrastructure platform repository
├── machine/                # Machine setup infrastructure
├── scripts/                # Platform utilities (legacy deployment)
└── docs/                   # Platform documentation

service/                    # Service catalog repository  
├── lldap/                  # LLDAP identity service
│   ├── docker-compose.yml
│   └── setup.sh
├── gazette/                # Future: Gazette service
├── redis/                  # Future: Redis service
└── prometheus/             # Future: Prometheus service

Migration Steps#

Phase 1: Prepare Service Repository#

1. Create new service repository on GitHub/GitLab
2. Move service/ directory contents to new repo
3. Add service-specific README.md and documentation
4. Set up proper .gitignore for service repo

Phase 2: Update tinsnip References#

1. Remove service/ directory from tinsnip repo
2. Update install.sh to optionally clone service repo
3. Update documentation to reference service repo
4. Modify deployment scripts to work with external service repo

Phase 3: Documentation Updates#

tinsnip/CLAUDE.md#

• Remove service-specific paths from project structure
• Add reference to external service repo
• Update deployment workflow to show service repo usage

tinsnip/README.md#

• Add section about companion service repository
• Update installation instructions

service/README.md (new)#

• Document service catalog structure
• Explain tinsnip service standards
• Provide template for new services

Phase 4: Update Installation Process#

Modify install.sh to:

# Clone tinsnip platform
git clone https://github.com/user/tinsnip.git

# Optionally clone service catalog
read -p "Clone service catalog? (y/N): " response
if [[ "$response" =~ ^[Yy]$ ]]; then
    git clone https://github.com/user/service.git tinsnip/service
fi

Phase 5: Service Deployment Changes#

Update deployment workflow to support:

1. Services from the official catalog (service repo)
2. Custom/private service repositories
3. Local service definitions

Example deployment:

# Using official service catalog
cd ~/.local/opt/tinsnip/service/lldap
./setup.sh

# Using custom service
cd ~/my-services/custom-app
TINSNIP_PATH=~/.local/opt/tinsnip ./setup.sh

Benefits of Separation#

1. Clean Architecture: Platform vs applications clearly separated
2. Independent Versioning: Platform stable while services evolve
3. Multiple Service Catalogs: Organizations can maintain private service repos
4. Simpler Platform: tinsnip focuses purely on infrastructure
5. Service Innovation: Easier to contribute new services without touching platform

Compatibility Considerations#

1. Backward Compatibility: Support existing deployments with services in subdirectory
2. Service Discovery: Platform can work with services from any location
3. Registry Updates: Service registry remains in namespace station, works across repos

Next Steps#

1. Create the new service repository
2. Test migration with lldap service
3. Update all documentation
4. Create migration script for existing deployments
5. Announce breaking change with migration guide