# Bangstack Examples

Real-world examples demonstrating how to build production-ready applications with Bangstack.

## Overview

These examples show complete, practical workflows covering different architectural patterns and use cases. Each example includes:

- ✅ Complete workflow YAML configuration
- ✅ Detailed README with step-by-step tutorials
- ✅ Real-world scenarios and use cases
- ✅ Version management workflows
- ✅ Deployment strategies
- ✅ Best practices and patterns

## Examples

### 1. [E-commerce API Platform](./ecommerce-api/)

**Best for**: Learning Bangstack basics, backend-only applications

A complete e-commerce backend API demonstrating:
- Backend API with multiple services (Redis, Queue, Email)
- Background worker for async processing
- Multi-environment configuration (local/staging/production)
- Version management basics
- Service dependency tracking

**Architecture**: Single API + Worker
**Complexity**: ⭐⭐ Beginner-friendly
**Services**: Redis, Queue, Email

```bash
cd examples/ecommerce-api
bang generate ecommerce.workflow.yaml
```

[View Example →](./ecommerce-api/)

---

### 2. [SaaS Full-Stack Platform](./saas-fullstack/)

**Best for**: Full-stack applications, real-time features

A complete SaaS analytics platform with:
- React frontend with analytics tracking
- Express API backend
- Real-time WebSocket server
- Background data processor
- Multi-database architecture
- Advanced caching and rate limiting

**Architecture**: Frontend + API + WebSocket + Workers
**Complexity**: ⭐⭐⭐ Intermediate
**Services**: Redis, Queue, Email, Analytics

```bash
cd examples/saas-fullstack
bang generate saas-platform.workflow.yaml
```

[View Example →](./saas-fullstack/)

---

### 3. [Multi-Tenant API Platform](./api-platform/)

**Best for**: Microservices, enterprise applications

A production-ready microservices platform with:
- API Gateway with routing and rate limiting
- 5 independent microservices
- Service mesh patterns
- Multi-tenancy support
- Circuit breakers and fallbacks
- Kubernetes deployment

**Architecture**: Gateway + 5 Microservices + 2 Workers
**Complexity**: ⭐⭐⭐⭐ Advanced
**Services**: Redis, Queue, Email, SMS, Analytics

```bash
cd examples/api-platform
bang generate api-platform.workflow.yaml
```

[View Example →](./api-platform/)

---

## Quick Comparison

| Feature | E-commerce | SaaS Platform | API Platform |
|---------|------------|---------------|--------------|
| Frontend | ❌ | ✅ React | ❌ |
| Backend Services | 1 API | 3 Services | 6 Services |
| Workers | 1 | 1 | 2 |
| Real-time | ❌ | ✅ WebSocket | ❌ |
| Microservices | ❌ | ❌ | ✅ |
| Multi-tenant | ❌ | ❌ | ✅ |
| Kubernetes | ❌ | ❌ | ✅ |
| Databases | 1 | 2 | 3 |
| Setup Time | ~5 min | ~10 min | ~15 min |

## Learning Path

### For Beginners

1. Start with **E-commerce API** to learn:
   - Basic workflow configuration
   - Service dependencies
   - Local development setup
   - Version management basics

2. Move to **SaaS Platform** to add:
   - Frontend integration
   - Real-time features
   - Multi-database patterns
   - Advanced caching

3. Tackle **API Platform** for:
   - Microservices architecture
   - Service mesh patterns
   - Multi-tenancy
   - Production deployment

### By Use Case

**Building a Marketplace?**
→ Start with E-commerce API, add real-time from SaaS Platform

**Building a Dashboard?**
→ Start with SaaS Platform, add microservices from API Platform

**Building an API Product?**
→ Go straight to API Platform

**Building a Mobile Backend?**
→ Start with E-commerce API, add real-time from SaaS Platform

## Common Patterns Across Examples

### 1. Version Management Workflow

All examples demonstrate:

```bash
# Make changes to workflow
vim example.workflow.yaml

# Verify before committing
bang verify example.workflow.yaml

# Generate code
bang generate example.workflow.yaml

# Test locally
npm test

# Create version
bang version create 1.1.0 -w example.workflow.yaml

# Deploy
git push origin 1.1.0
```

### 2. Multi-Environment Configuration

All examples support:
- **Local**: Docker Compose with local services
- **Staging**: Cloud services for testing
- **Production**: Production-grade infrastructure

### 3. Service Integration Patterns

All examples show how to:
- Generate service clients automatically
- Use services in your code
- Handle errors and fallbacks
- Test with mock services

### 4. Development Workflow

All examples include:

```bash
# Start infrastructure
docker-compose up -d

# Install dependencies
npm install

# Run migrations
npm run migrate

# Start development
npm run dev

# Run tests
npm test
```

## Best Practices Demonstrated

### Infrastructure as Code

```yaml
# Declare your infrastructure in YAML
stages:
  production:
    services:
      redis:
        provider: upstash
        connection: "{{secrets.REDIS_URL}}"
```

### Dependency Tracking

```yaml
# Declare what each component needs
expected_dependencies:
  - service: redis
    usage: Session storage
    required: true
```

### Version Management

```bash
# Track changes over time
bang version create 1.0.0
bang version diff 1.0.0 2.0.0
bang version rollback 1.0.0
```

### CI/CD Integration

All examples generate GitHub Actions workflows:
- Run tests on PR
- Deploy to staging on merge
- Deploy to production on version tag

## Running the Examples

### Prerequisites

```bash
# Install Bangstack
npm install -g bangstack

# Install Docker
# https://docs.docker.com/get-docker/

# Clone the repository
git clone https://github.com/yourusername/bangstack
cd bangstack/examples
```

### Try an Example

```bash
# Pick an example
cd ecommerce-api   # or saas-fullstack or api-platform

# Generate the project
bang generate *.workflow.yaml

# Start development
docker-compose up -d
npm install
npm run dev
```

### Modify an Example

```bash
# 1. Make changes to the workflow file
vim ecommerce.workflow.yaml

# 2. Verify changes
bang verify ecommerce.workflow.yaml

# 3. Regenerate
bang generate ecommerce.workflow.yaml

# 4. Test your changes
npm test
```

## Troubleshooting

### Port Already in Use

```bash
# Change ports in workflow file
api:
  port: 4000  # Change this

# Or stop conflicting services
docker-compose down
```

### Service Connection Failed

```bash
# Check services are running
docker-compose ps

# Check logs
docker-compose logs redis
docker-compose logs postgres
```

### Generate Failed

```bash
# Validate workflow first
bang verify example.workflow.yaml

# Check for errors
cat .bangstack/manifest.json
```

## Contributing Examples

Want to add your own example? Great!

1. Create a new directory in `examples/`
2. Add a workflow YAML file
3. Add a comprehensive README.md
4. Include real-world scenarios
5. Submit a PR

See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.

## Learn More

- [Bangstack Documentation](../README.md)
- [Workflow Schema Reference](../docs/workflow-schema.md)
- [Version Management Guide](../README.md#version-management)
- [CLI Commands](../README.md#cli-commands)

## Get Help

- 💬 [Discord Community](https://discord.gg/bangstack)
- 🐛 [Report Issues](https://github.com/yourusername/bangstack/issues)
- 📖 [Full Documentation](../README.md)
- ✨ [Request Features](https://github.com/yourusername/bangstack/discussions)

## Next Steps

1. **Choose an example** that matches your use case
2. **Generate the project** and explore the code
3. **Modify the workflow** to fit your needs
4. **Deploy to staging** and test it out
5. **Share your experience** with the community

Happy building! 🚀
