pos-system/README.md

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

# 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

# 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
• API Documentation
• Development Guide
• Deployment Guide
• Contributing Guide

🔐 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

# 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

# Build all packages and services
pnpm build

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

🚢 Deployment

See Deployment Guide for detailed instructions.

Quick Deploy

# 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 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 file for details.

👥 Team

Built with ❤️ by the GoodGo team