201 lines
5.0 KiB
Markdown
201 lines
5.0 KiB
Markdown
# 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
|