From a6446c097542d8996e6332b18c611a3660a29073 Mon Sep 17 00:00:00 2001 From: 0x1d Date: Wed, 5 Nov 2025 21:42:24 +0100 Subject: [PATCH] docs: update readme --- AGENTS.md | 6 ++--- README.md | 28 ++++------------------- docs/content/architecture/architecture.md | 2 +- docs/content/index.md | 2 +- docs/content/plan.md | 2 +- docs/content/playbook.md | 2 +- 6 files changed, 12 insertions(+), 30 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0d29a5b..71a3d2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -189,7 +189,7 @@ When working on this project, follow this workflow: - Implement tests ### 6. Verify Alignment -- Ensure code follows Clean/Hexagonal Architecture principles +- Ensure code follows Hexagonal Architecture principles - Verify it aligns with microservices architecture - Check that it follows plugin-first design - Confirm security-by-design principles are followed @@ -210,7 +210,7 @@ When working on this project, follow this workflow: The project follows these core principles (documented in `requirements.md` and `playbook.md`): -1. **Clean/Hexagonal Architecture** +1. **Hexagonal Architecture** - Clear separation between `pkg/` (interfaces) and `internal/` (implementations) - Domain code in `internal/domain` - Only interfaces exported from `pkg/` @@ -272,7 +272,7 @@ After implementing a feature, verify: 2. **Committing without verification** - Never commit code that doesn't build, has failing tests, or doesn't meet acceptance criteria 3. **Implementing without checking stories** - Stories contain specific deliverables and acceptance criteria 4. **Ignoring ADRs** - ADRs document why decisions were made; don't reinvent the wheel -5. **Violating architecture principles** - Code must follow Clean/Hexagonal Architecture +5. **Violating architecture principles** - Code must follow Hexagonal Architecture 6. **Missing acceptance criteria** - All stories have specific criteria that must be met 7. **Not following module patterns** - Modules must implement the `IModule` interface correctly 8. **Skipping observability** - All features must include proper logging, metrics, and tracing diff --git a/README.md b/README.md index 47dc247..7ad2566 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Go Platform (goplt) +# Go Platform -**Plugin-friendly SaaS/Enterprise Platform – Go Edition** +**SaaS/Enterprise Platform – Go Edition** A modular, extensible platform built with Go that provides a solid foundation for building scalable, secure, and observable applications. The platform supports plugin-based architecture, enabling teams to build feature modules independently while sharing core services. @@ -14,15 +14,6 @@ Go Platform follows **Clean/Hexagonal Architecture** principles with clear separ - **Security-by-Design**: Built-in JWT authentication, RBAC/ABAC authorization, and audit logging - **Observability**: OpenTelemetry integration for tracing, metrics, and logging -### Key Principles - -- **Clean Architecture**: Separation between `pkg/` (interfaces) and `internal/` (implementations) -- **Dependency Injection**: Using `uber-go/fx` for lifecycle management -- **Microservices-Ready**: Each module is an independent service from day one -- **Plugin-First Design**: Extensible architecture supporting static and dynamic module loading -- **Security-by-Design**: JWT authentication, RBAC/ABAC, and audit logging -- **Observability**: OpenTelemetry, structured logging, and Prometheus metrics - ## Directory Structure ``` @@ -40,7 +31,7 @@ goplt/ ├── pkg/ # Public interfaces (exported) │ ├── config/ # ConfigProvider interface │ ├── logger/ # Logger interface -│ ├── module/ # IModule interface +│ ├── module/ # IModule interface │ ├── auth/ # Auth interfaces │ ├── perm/ # Permission DSL │ └── infra/ # Infrastructure interfaces @@ -212,7 +203,7 @@ type IModule interface { - **Structured Logging**: JSON-formatted logs with correlation IDs - **Health Checks**: Kubernetes-ready health and readiness endpoints -## 🔧 Configuration +## Configuration Configuration is managed through YAML files and environment variables. See `config/default.yaml` for the base configuration structure. @@ -223,15 +214,6 @@ Key configuration sections: - **Logging**: Log level, format, and output destination - **Authentication**: JWT settings and token configuration -## Testing - -The project follows table-driven testing patterns and includes: - -- Unit tests for all packages -- Integration tests for service interactions -- Mock generation for interfaces -- Test coverage reporting - ## Contributing 1. Create a feature branch: `git checkout -b feature/my-feature` @@ -251,6 +233,6 @@ The project follows table-driven testing patterns and includes: - [Implementation Plan](docs/content/plan.md) - [Playbook](docs/content/playbook.md) -## 📞 Support +## Support For questions and support, please refer to the documentation or create an issue in the repository. diff --git a/docs/content/architecture/architecture.md b/docs/content/architecture/architecture.md index 50bc88f..bd67818 100644 --- a/docs/content/architecture/architecture.md +++ b/docs/content/architecture/architecture.md @@ -69,7 +69,7 @@ graph TB ## Layered Architecture -The platform follows a **clean/hexagonal architecture** with clear separation of concerns across layers. +The platform follows a **hexagonal architecture** with clear separation of concerns across layers. ```mermaid graph TD diff --git a/docs/content/index.md b/docs/content/index.md index 290de60..a678fc6 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -63,7 +63,7 @@ Detailed task definitions for each epic are available in the [Stories section](s ## Key Principles -- **Clean/Hexagonal Architecture**: Clear separation between core and plugins +- **Hexagonal Architecture**: Clear separation between core and plugins - **Microservices Architecture**: Each module is an independent service from day one - **Plugin-First Design**: Extensible architecture supporting static and dynamic modules - **Security-by-Design**: Built-in authentication, authorization, and audit capabilities diff --git a/docs/content/plan.md b/docs/content/plan.md index 1ca30d2..38d4612 100644 --- a/docs/content/plan.md +++ b/docs/content/plan.md @@ -13,7 +13,7 @@ This plan breaks down the implementation into **8 epics**, each with specific de **Total Estimated Timeline:** 8-12 weeks (depending on team size and parallelization) **Key Principles:** -- **Clean/Hexagonal Architecture** with clear separation between `pkg/` (interfaces) and `internal/` (implementations) +- **Hexagonal Architecture** with clear separation between `pkg/` (interfaces) and `internal/` (implementations) - **Dependency Injection** using `uber-go/fx` for lifecycle management - **Microservices Architecture** - each module is an independent service from day one - **Service Client Interfaces** - all inter-service communication via gRPC/HTTP diff --git a/docs/content/playbook.md b/docs/content/playbook.md index c8cd714..68e2fca 100644 --- a/docs/content/playbook.md +++ b/docs/content/playbook.md @@ -5,7 +5,7 @@ | Principle | Go‑specific rationale | Enforcement Technique | |-----------|-----------------------|------------------------| -| **Clean / Hexagonal Architecture** | Go’s package‑level visibility (`internal/`) naturally creates a *boundary* between core and plug‑ins. | Keep all **domain** code in `internal/domain`, expose only **interfaces** in `pkg/`. | +| **Hexagonal Architecture** | Go’s package‑level visibility (`internal/`) naturally creates a *boundary* between core and plug‑ins. | Keep all **domain** code in `internal/domain`, expose only **interfaces** in `pkg/`. | | **Dependency Injection (DI) via Constructors** | Go avoids reflection‑heavy containers; compile‑time wiring is preferred. | Use **uber‑go/fx** (runtime graph) *or* **uber‑go/dig** for optional runtime DI. For a lighter weight solution, use plain **constructor injection** with a small **registry**. | | **Modular Monolith → Micro‑service‑ready** | A single binary is cheap in Go; later you can extract modules into separate services without breaking APIs. | Each module lives in its own Go **module** (`go.mod`) under `./modules/*`. The core loads them via the **Go plugin** system *or* static registration (preferred for CI stability). | | **Plugin‑first design** | Go’s `plugin` package allows runtime loading of compiled `.so` files (Linux/macOS). | Provide an **IModule** interface and a **loader** that discovers `*.so` files (or compiled‑in modules for CI). |