# Go Platform Documentation

Welcome to the Go Platform documentation! This is a plugin-friendly SaaS/Enterprise platform built with Go.

## What is Go Platform?

Go Platform is a microservices platform designed to support multiple business domains through independent, deployable services. It provides:

- **Core Kernel**: Infrastructure only (configuration, logging, DI, health, metrics, observability) - no business logic
- **Core Services**: Independent microservices (Auth, Identity, Authz, Audit) with their own entry points and databases
- **API Gateway**: Single entry point for all external traffic, handles routing, authentication, and rate limiting
- **Service Discovery**: Consul-based service registry for dynamic service discovery
- **Module Framework**: Feature services (Blog, Billing, etc.) as independent services
- **Infrastructure Adapters**: Support for databases, caching, event buses, and job scheduling
- **Security-by-Design**: Built-in JWT authentication, RBAC/ABAC authorization, and audit logging
- **Observability**: OpenTelemetry integration for distributed tracing, metrics, and logging across services

## Documentation Structure

### Overview
- **[Requirements](requirements.md)**: High-level architectural principles and requirements
- **[Implementation Plan](plan.md)**: Epic-based implementation plan with timelines
- **[Playbook](playbook.md)**: Detailed implementation guide and best practices

### Architecture
- **[Architecture Overview](architecture/architecture.md)**: System architecture with diagrams
- **[Module Architecture](architecture/architecture-modules.md)**: Module system design and integration
- **[Module Requirements](architecture/module-requirements.md)**: Detailed requirements for each module
- **[Component Relationships](architecture/component-relationships.md)**: Component interactions and dependencies
- **System Specifications**
  - **[System Behavior Overview](architecture/system-behavior.md)**: How the system behaves end-to-end
  - **[Service Orchestration](architecture/service-orchestration.md)**: How services work together
  - **[Module Integration Patterns](architecture/module-integration-patterns.md)**: How modules integrate with the platform
  - **[Operational Scenarios](architecture/operational-scenarios.md)**: Common operational flows and use cases
  - **[Data Flow Patterns](architecture/data-flow-patterns.md)**: How data flows through the system

### Architecture Decision Records (ADRs)
All architectural decisions are documented in [ADR records](adr/README.md), organized by implementation epic:  

- **Epic 0**: Project Setup & Foundation
- **Epic 1**: Core Kernel & Infrastructure
- **Epic 2**: Authentication & Authorization
- **Epic 3**: Module Framework
- **Epic 5**: Infrastructure Adapters
- **Epic 6**: Observability & Production Readiness
- **Epic 7**: Testing, Documentation & CI/CD

### Implementation Tasks
Detailed task definitions for each epic are available in the [Stories section](stories/README.md):

- **[Epic 0: Project Setup & Foundation](stories/epic0/README.md)** - [Implementation Summary](stories/epic0/SUMMARY.md)
- **[Epic 1: Core Kernel & Infrastructure](stories/epic1/README.md)** - [Implementation Summary](stories/epic1/SUMMARY.md)
- Epic 2: Authentication & Authorization
- Epic 3: Module Framework
- Epic 4: Sample Feature Module (Blog)
- Epic 5: Infrastructure Adapters
- Epic 6: Observability & Production Readiness
- Epic 7: Testing, Documentation & CI/CD
- Epic 8: Advanced Features & Polish (Optional)

## Quick Start

1. Review the [Requirements](requirements.md) to understand the platform goals
2. Check the [Implementation Plan](plan.md) for the epic-based approach
3. Follow the [Playbook](playbook.md) for implementation details
4. Refer to [ADRs](adr/README.md) when making architectural decisions
5. Use the [Task Stories](stories/README.md) as a checklist for implementation

## Key Principles

- **microMicroservices Architecture**: Each service is independently deployable from day one
  - Core Kernel: Infrastructure only (config, logger, DI, health, metrics)
  - Core Services: Auth, Identity, Authz, Audit as separate services
  - Feature Services: Blog, Billing, etc. as independent services
- **API Gateway**: Single entry point for all external traffic
- **Service Discovery**: Consul-based service registry for dynamic service location
- **Service Clients**: All inter-service communication via gRPC/HTTP through service clients
- **Database Isolation**: Each service has its own database connection pool and schema
- **Hexagonal Architecture**: Clear separation between interfaces and implementations
- **Security-by-Design**: Built-in authentication, authorization, and audit capabilities
- **Observability**: Comprehensive distributed tracing, metrics, and logging across services
- **API-First**: OpenAPI/GraphQL schema generation

## Contributing

When contributing to the platform:
1. Review relevant ADRs before making architectural decisions
2. Follow the task structure defined in the Stories
3. Update documentation as you implement features
4. Ensure all tests pass before submitting changes