# GoodGo Microservices Platform

Enterprise-grade microservices monorepo built with modern technologies and best practices.

## 🏗️ Architecture

This monorepo follows a microservices architecture pattern with:

- **Apps**: Frontend applications (Web + Mobile)
- **Services**: Backend microservices (starting with Auth Service)
- **Packages**: Shared libraries and utilities
- **Infrastructure**: Traefik, Observability, Databases
- **Deployments**: Environment-specific configurations

## 📁 Project Structure

```
├── apps/                 # Frontend applications
│   ├── web-admin/       # Next.js admin web application
│   ├── web-client/      # Next.js client web application
│   ├── app-admin/       # Flutter admin mobile application
│   └── app-client/      # Flutter client mobile application
├── services/            # Backend microservices
│   ├── auth-service/    # Authentication service
│   └── _template/       # Service template
├── packages/            # Shared libraries
│   ├── logger/          # Centralized logging
│   ├── types/           # TypeScript types
│   ├── config/          # Shared configs
│   ├── http-client/     # API client wrapper
│   ├── auth-sdk/        # Auth utilities
│   └── tracing/         # OpenTelemetry setup
├── infra/               # Infrastructure as Code
│   ├── traefik/         # Traefik configuration
│   ├── docker/          # Docker configs
│   ├── observability/   # Monitoring stack
│   └── databases/       # Database configs
├── deployments/         # Environment configs
│   ├── local/           # Local development
│   ├── staging/         # Staging environment
│   └── production/      # Production environment
├── .github/             # CI/CD workflows
├── scripts/             # Automation scripts
└── docs/                # Documentation
```

## 🚀 Getting Started

### Prerequisites

- Node.js >= 20.0.0
- pnpm >= 8.0.0
- Docker & Docker Compose
- Neon account (https://neon.tech) - for PostgreSQL database

### Installation

```bash
# Install dependencies
pnpm install

# Start all services (development)
pnpm dev

# Start specific service
pnpm --filter @goodgo/auth-service dev

# Build all
pnpm build

# Run tests
pnpm test

# Run linter
pnpm lint
```

### Local Development

```bash
# Setup Neon database (first time only)
./scripts/db/setup-neon.sh
# Or manually: Create .env.local with Neon DATABASE_URL

# Start infrastructure (Redis, Traefik - no PostgreSQL needed)
cd deployments/local
docker-compose up -d

# Run migrations
./scripts/db/migrate.sh auth-service dev

# Start services
pnpm dev
```

**Note**: This project uses Neon PostgreSQL. No local PostgreSQL setup needed!

## 🛠️ Tech Stack

**Frontend:**
- Web: Next.js 14+ (App Router) - Admin & Client portals
- Mobile: Flutter 3.x - Admin & Client apps
- TypeScript / Dart
- Tailwind CSS
- Zustand / Provider

**Backend:**
- Node.js + TypeScript
- Express/NestJS
- Prisma ORM
- PostgreSQL (Neon - serverless)
- Redis

**Infrastructure:**
- Traefik (API Gateway)
- Docker & Docker Compose
- Kubernetes (production)
- Prometheus + Grafana + Loki
- OpenTelemetry

**DevOps:**
- GitHub Actions
- PNPM Workspaces
- Turborepo

## 📚 Documentation

- [Architecture Overview](docs/architecture/system-design.md)
- [API Documentation](docs/api/openapi/)
- [Development Guide](docs/guides/development.md)
- [Deployment Guide](docs/guides/deployment.md)
- [Contributing Guide](CONTRIBUTING.md)

## 🔐 Environment Variables

### Database (Neon)

All environments use Neon PostgreSQL:
- **Dev**: Set `DATABASE_URL` in `deployments/local/.env.local`
- **Staging/Prod**: Set in Kubernetes secrets or GitHub Secrets

See `infra/databases/neon/README.md` for setup instructions.

### Other Variables

Copy `.env.example` files in each service/app and configure accordingly.

**Important**: Never commit `.env` files. Use `.env.example` as templates.

## 🧪 Testing

```bash
# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @goodgo/auth-service test

# Run with coverage
pnpm --filter @goodgo/auth-service test:coverage
```

## 📦 Building

```bash
# Build all packages and services
pnpm build

# Build specific service
pnpm --filter @goodgo/auth-service build
```

## 🚢 Deployment

See [Deployment Guide](docs/guides/deployment.md) for detailed instructions.

### Quick Deploy

```bash
# Local
cd deployments/local && docker-compose up -d

# Staging (Kubernetes)
cd deployments/staging && kubectl apply -f kubernetes/

# Production
cd deployments/production && kubectl apply -f kubernetes/
```

## 🤝 Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 👥 Team

Built with ❤️ by the GoodGo team