lucidia-core/templates/README-TEMPLATE.md

# [Service/Feature Name]

**One-line description of what this does**

## Quick Start (Copy-Paste Ready)

```bash
# Clone and setup
cd ~/blackroad-sandbox
git pull origin main

# Install dependencies
pip3 install -r requirements.txt

# Start service
PORT=8000 python3 blackroad-service.py

# Verify it's running
curl http://localhost:8000/health
```

---

## What This Does

[2-3 sentence explanation of purpose and value]

---

## Installation

### Local Development

```bash
# Navigate to project
cd ~/blackroad-sandbox

# Install Python dependencies
pip3 install -r requirements.txt

# Copy environment template
cp .env.example .env

# Add your secrets
cat >> .env <<'EOF'
SERVICE_TOKEN=your-token-here
API_KEY=your-key-here
EOF

# Verify installation
python3 -c "import flask; print('✅ Dependencies installed')"
```

### Docker

```bash
# Build image
docker build -t blackroad-service .

# Run container
docker run -p 8000:8000 --env-file .env blackroad-service

# Verify
curl http://localhost:8000/health
```

---

## Usage

### Start the Service

```bash
# Development mode
PORT=8000 python3 blackroad-service.py

# Production mode
FLASK_ENV=production PORT=8000 python3 blackroad-service.py

# With Docker Compose
docker-compose up -d service-name
```

### Test the Service

```bash
# Health check
curl http://localhost:8000/health

# Test specific endpoint
curl http://localhost:8000/api/resource -X POST -H "Content-Type: application/json" -d '{"key":"value"}'

# Run automated tests
pytest tests/test_service.py -v
```

### Deploy to Production

```bash
# Deploy to Railway
cd ~/blackroad-sandbox
railway up --service service-name

# Deploy to Cloudflare
cd cloudflare-workers
wrangler deploy service.js --config wrangler-service.toml

# Verify deployment
curl https://service.blackroad.io/health
```

---

## API Reference

### Endpoints

#### `GET /health`

Health check endpoint.

```bash
# Example
curl http://localhost:8000/health
```

**Response:**
```json
{
  "ok": true,
  "service": "service-name",
  "version": "1.0.0"
}
```

#### `POST /api/resource`

Create a new resource.

```bash
# Example
curl http://localhost:8000/api/resource \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"example","value":42}'
```

**Response:**
```json
{
  "ok": true,
  "resource_id": "abc123"
}
```

---

## Configuration

### Environment Variables

```bash
# Required
SERVICE_TOKEN=your-service-token
API_KEY=your-api-key

# Optional
PORT=8000
LOG_LEVEL=info
ENVIRONMENT=production
```

### Config Files

- `.env` - Environment variables
- `config.yaml` - Service configuration
- `railway.toml` - Railway deployment config

---

## Development

### Running Tests

```bash
# All tests
pytest -v

# Unit tests only
pytest -m unit -v

# Integration tests
pytest -m integration -v

# With coverage
pytest --cov=. --cov-report=html
open coverage_html/index.html
```

### Local Development Workflow

```bash
# 1. Create feature branch
git checkout -b feature/new-feature

# 2. Make changes
# Edit files...

# 3. Test locally
pytest -v
python3 blackroad-service.py

# 4. Commit
git add .
git commit -m "feat: Add new feature"

# 5. Push
git push -u origin feature/new-feature

# 6. Create PR
gh pr create --title "Add new feature" --body "Description"
```

---

## Deployment

### Railway

```bash
# Link to project
railway link 0c7bcf07-307b-4db6-9c94-22a456500d68

# Deploy
railway up --service service-name

# Check status
railway status

# View logs
railway logs --tail 100
```

### Cloudflare Pages/Workers

```bash
# Deploy worker
cd cloudflare-workers
wrangler deploy service.js --config wrangler-service.toml

# Deploy page
cd domains/domain-name
wrangler pages deploy . --project-name=domain-name

# Check deployment
wrangler pages deployment list --project-name=domain-name
```

### Vercel

```bash
# Deploy
cd vercel-projects/project-name
vercel --prod

# Check deployment
vercel ls
```

---

## Troubleshooting

### Service Won't Start

```bash
# Check if port is in use
lsof -i :8000

# Kill existing process
kill -9 $(lsof -t -i:8000)

# Restart service
PORT=8000 python3 blackroad-service.py
```

### Import Errors

```bash
# Reinstall dependencies
pip3 install -r requirements.txt --force-reinstall

# Verify Python version
python3 --version  # Should be 3.11+

# Check imports
python3 -c "import flask; print('✅ Flask OK')"
```

### Environment Variables Not Loaded

```bash
# Check .env exists
ls -la .env

# Source manually
source .env

# Verify variables
echo $SERVICE_TOKEN
```

### Deployment Failed

```bash
# Railway
railway logs --tail 100
railway status
railway variables  # Check secrets are set

# Cloudflare
wrangler tail  # View live logs
wrangler pages deployment list --project-name=PROJECT_NAME
```

---

## Architecture

[Diagram or description of how this service fits into the larger system]

---

## Contributing

```bash
# 1. Fork/clone
git clone https://github.com/BlackRoad-OS/repo-name.git

# 2. Create branch
git checkout -b feature/your-feature

# 3. Make changes and test
pytest -v

# 4. Commit with conventional commits
git commit -m "feat: Add your feature"

# 5. Push
git push -u origin feature/your-feature

# 6. Create PR
gh pr create
```

---

## License

```
# ============================================================================
# BlackRoad OS - Proprietary Software
# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
# All Rights Reserved.
# ============================================================================
```

---

## Support

- **Email**: blackroad.systems@gmail.com
- **Docs**: [Link to docs]
- **Issues**: [Link to GitHub issues]

---

## Related Services

- [Service 1](link) - Description
- [Service 2](link) - Description
- [Service 3](link) - Description

---

**Quick Links**:
- [API Documentation](link)
- [Deployment Guide](link)
- [Troubleshooting](link)