0x1d
38a251968c
Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.
Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
- Each service has own entry point (cmd/{service}/)
- Each service has own gRPC server and database schema
- Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
- Single entry point for all external traffic
- Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation
Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files
New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)
New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation
90 lines
5.0 KiB
Markdown
90 lines
5.0 KiB
Markdown
# 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
|
|
|