From 66b0c3b40d4f1ec811c81d5ac70abf829515e4a8 Mon Sep 17 00:00:00 2001 From: 0x1d Date: Wed, 5 Nov 2025 11:00:36 +0100 Subject: [PATCH] docs: update dead links --- docs/content/adr/0006-http-framework.md | 2 +- docs/content/adr/0010-ci-cd-platform.md | 2 +- docs/content/adr/0013-database-orm.md | 2 +- .../adr/0016-opentelemetry-observability.md | 2 +- .../architecture-modules.md | 0 .../{ => architecture}/architecture.md | 0 .../component-relationships.md | 0 .../{ => architecture}/data-flow-patterns.md | 0 .../module-integration-patterns.md | 0 .../{ => architecture}/module-requirements.md | 0 .../operational-scenarios.md | 0 .../service-orchestration.md | 4 +- .../{ => architecture}/system-behavior.md | 0 docs/content/index.md | 21 ++--- docs/content/plan.md | 3 +- docs/content/stories/COMPLETE_TASK_LIST.md | 91 +++++++++++++------ docs/content/stories/TASK_TEMPLATE.md | 2 +- docs/content/stories/generate_tasks.py | 43 ++++----- docs/content/versions.json | 9 ++ docs/mkdocs.yml | 28 +++--- 20 files changed, 126 insertions(+), 83 deletions(-) rename docs/content/{ => architecture}/architecture-modules.md (100%) rename docs/content/{ => architecture}/architecture.md (100%) rename docs/content/{ => architecture}/component-relationships.md (100%) rename docs/content/{ => architecture}/data-flow-patterns.md (100%) rename docs/content/{ => architecture}/module-integration-patterns.md (100%) rename docs/content/{ => architecture}/module-requirements.md (100%) rename docs/content/{ => architecture}/operational-scenarios.md (100%) rename docs/content/{ => architecture}/service-orchestration.md (98%) rename docs/content/{ => architecture}/system-behavior.md (100%) create mode 100644 docs/content/versions.json diff --git a/docs/content/adr/0006-http-framework.md b/docs/content/adr/0006-http-framework.md index 0d9cdfe..48519b3 100644 --- a/docs/content/adr/0006-http-framework.md +++ b/docs/content/adr/0006-http-framework.md @@ -27,7 +27,7 @@ Use **gin-gonic/gin** (v1.9.1+) as the HTTP framework. - Easy route grouping (useful for modules) - Good OpenTelemetry integration support - Widely used and well-documented -- Recommended in playbook-golang.md +- Recommended in playbook.md ## Consequences diff --git a/docs/content/adr/0010-ci-cd-platform.md b/docs/content/adr/0010-ci-cd-platform.md index 90f7863..a5a8960 100644 --- a/docs/content/adr/0010-ci-cd-platform.md +++ b/docs/content/adr/0010-ci-cd-platform.md @@ -26,7 +26,7 @@ Use **GitHub Actions** for CI/CD pipeline. - Rich ecosystem of actions - Easy to configure with YAML - Good documentation and community support -- Recommended in playbook-golang.md +- Recommended in playbook.md ## Consequences diff --git a/docs/content/adr/0013-database-orm.md b/docs/content/adr/0013-database-orm.md index 068fecf..91e0d16 100644 --- a/docs/content/adr/0013-database-orm.md +++ b/docs/content/adr/0013-database-orm.md @@ -27,7 +27,7 @@ Use **entgo.io/ent** as the primary ORM for the platform. - Strong relationship modeling - Good performance (no reflection at runtime) - Active development and good documentation -- Recommended in playbook-golang.md +- Recommended in playbook.md - Easy to integrate with OpenTelemetry ## Consequences diff --git a/docs/content/adr/0016-opentelemetry-observability.md b/docs/content/adr/0016-opentelemetry-observability.md index 19244db..95edec5 100644 --- a/docs/content/adr/0016-opentelemetry-observability.md +++ b/docs/content/adr/0016-opentelemetry-observability.md @@ -29,7 +29,7 @@ Use **OpenTelemetry (OTEL)** for all observability: - Excellent Go SDK support - Integrates with major observability tools - Supports metrics, traces, and logs -- Recommended in playbook-golang.md +- Recommended in playbook.md - Future-proof (not locked to specific vendor) ## Consequences diff --git a/docs/content/architecture-modules.md b/docs/content/architecture/architecture-modules.md similarity index 100% rename from docs/content/architecture-modules.md rename to docs/content/architecture/architecture-modules.md diff --git a/docs/content/architecture.md b/docs/content/architecture/architecture.md similarity index 100% rename from docs/content/architecture.md rename to docs/content/architecture/architecture.md diff --git a/docs/content/component-relationships.md b/docs/content/architecture/component-relationships.md similarity index 100% rename from docs/content/component-relationships.md rename to docs/content/architecture/component-relationships.md diff --git a/docs/content/data-flow-patterns.md b/docs/content/architecture/data-flow-patterns.md similarity index 100% rename from docs/content/data-flow-patterns.md rename to docs/content/architecture/data-flow-patterns.md diff --git a/docs/content/module-integration-patterns.md b/docs/content/architecture/module-integration-patterns.md similarity index 100% rename from docs/content/module-integration-patterns.md rename to docs/content/architecture/module-integration-patterns.md diff --git a/docs/content/module-requirements.md b/docs/content/architecture/module-requirements.md similarity index 100% rename from docs/content/module-requirements.md rename to docs/content/architecture/module-requirements.md diff --git a/docs/content/operational-scenarios.md b/docs/content/architecture/operational-scenarios.md similarity index 100% rename from docs/content/operational-scenarios.md rename to docs/content/architecture/operational-scenarios.md diff --git a/docs/content/service-orchestration.md b/docs/content/architecture/service-orchestration.md similarity index 98% rename from docs/content/service-orchestration.md rename to docs/content/architecture/service-orchestration.md index 4080f9a..56275ab 100644 --- a/docs/content/service-orchestration.md +++ b/docs/content/architecture/service-orchestration.md @@ -398,6 +398,6 @@ This service orchestration integrates with: - [Module Integration Patterns](module-integration-patterns.md) - Module service integration - [Operational Scenarios](operational-scenarios.md) - Service interaction scenarios - [Architecture Overview](architecture.md) - System architecture -- [ADR-0029: Microservices Architecture](adr/0029-microservices-architecture.md) - Architecture decision -- [ADR-0030: Service Communication Strategy](adr/0030-service-communication-strategy.md) - Communication patterns +- [ADR-0029: Microservices Architecture](../adr/0029-microservices-architecture.md) - Architecture decision +- [ADR-0030: Service Communication Strategy](../adr/0030-service-communication-strategy.md) - Communication patterns diff --git a/docs/content/system-behavior.md b/docs/content/architecture/system-behavior.md similarity index 100% rename from docs/content/system-behavior.md rename to docs/content/architecture/system-behavior.md diff --git a/docs/content/index.md b/docs/content/index.md index bcd816d..4943da5 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -20,17 +20,16 @@ Go Platform is a modular, extensible platform designed to support multiple busin - **[Playbook](playbook.md)**: Detailed implementation guide and best practices ### 🏛️ Architecture -- **[Architecture Overview](architecture.md)**: System architecture with diagrams -- **[Module Architecture](architecture-modules.md)**: Module system design and integration -- **[Module Requirements](module-requirements.md)**: Detailed requirements for each module -- **[Component Relationships](component-relationships.md)**: Component interactions and dependencies - -### 📐 System Specifications -- **[System Behavior Overview](system-behavior.md)**: How the system behaves end-to-end -- **[Service Orchestration](service-orchestration.md)**: How services work together -- **[Module Integration Patterns](module-integration-patterns.md)**: How modules integrate with the platform -- **[Operational Scenarios](operational-scenarios.md)**: Common operational flows and use cases -- **[Data Flow Patterns](data-flow-patterns.md)**: How data flows through the system +- **[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: diff --git a/docs/content/plan.md b/docs/content/plan.md index 5565c4e..1ca30d2 100644 --- a/docs/content/plan.md +++ b/docs/content/plan.md @@ -2,7 +2,7 @@ **"Plug‑in‑friendly SaaS/Enterprise Platform – Go Edition"** -> This document outlines a complete, epic-based implementation plan for building the Go platform boilerplate based on the requirements from `playbook.md` and `playbook-golang.md`. +> This document outlines a complete, epic-based implementation plan for building the Go platform boilerplate based on the requirements from `playbook.md`. --- @@ -1649,7 +1649,6 @@ The platform is considered complete when: ## References - [playbook.md](./playbook.md) - General platform playbook -- [playbook-golang.md](./playbook-golang.md) - Go-specific playbook - [Go Modules Documentation](https://go.dev/doc/modules) - [Ent Documentation](https://entgo.io/docs/getting-started) - [Uber FX Documentation](https://github.com/uber-go/fx) diff --git a/docs/content/stories/COMPLETE_TASK_LIST.md b/docs/content/stories/COMPLETE_TASK_LIST.md index 8d1d630..70a4d64 100644 --- a/docs/content/stories/COMPLETE_TASK_LIST.md +++ b/docs/content/stories/COMPLETE_TASK_LIST.md @@ -8,39 +8,76 @@ Tasks are organized by epic and section. Each task file follows the naming conve ## Epic 0: Project Setup & Foundation -### 0.1 Repository Bootstrap -- [0.1.1 - Initialize Go Module](./epic0/0.1.1-initialize-go-module.md) -- [0.1.2 - Create Directory Structure](./epic0/0.1.2-create-directory-structure.md) -- [0.1.3 - Add Gitignore](./epic0/0.1.3-add-gitignore.md) -- [0.1.4 - Create Initial README](./epic0/0.1.4-create-initial-readme.md) +### Epic 0 Stories +- [0.1 Project Initialization and Repository Structure](./epic0/0.1-project-initialization.md) +- [0.2 Configuration Management System](./epic0/0.2-configuration-management-system.md) +- [0.3 Structured Logging System](./epic0/0.3-structured-logging-system.md) +- [0.4 CI/CD Pipeline and Development Tooling](./epic0/0.4-cicd-pipeline.md) +- [0.5 Dependency Injection and Application Bootstrap](./epic0/0.5-di-and-bootstrap.md) -### 0.2 Configuration System -- [0.2.1 - Install Configuration Dependencies](./epic0/0.2.1-install-config-dependencies.md) -- [0.2.2 - Create Config Interface](./epic0/0.2.2-create-config-interface.md) -- [0.2.3 - Implement Config Loader](./epic0/0.2.3-implement-config-loader.md) -- [0.2.4 - Create Configuration Files](./epic0/0.2.4-create-configuration-files.md) +## Epic 1: Core Kernel & Infrastructure +- [1.1 Enhanced DI Container](./epic1/1.1-enhanced-di-container.md) +- [1.2 Database Layer](./epic1/1.2-database-layer.md) +- [1.3 Health & Metrics System](./epic1/1.3-health-metrics-system.md) +- [1.4 Error Handling](./epic1/1.4-error-handling.md) +- [1.5 HTTP Server](./epic1/1.5-http-server.md) +- [1.6 OpenTelemetry](./epic1/1.6-opentelemetry.md) +- [1.7 Service Client Interfaces](./epic1/1.7-service-abstraction-layer.md) +- [Epic 1 Overview](./epic1/README.md) -### 0.3 Logging Foundation -- [0.3.1 - Install Logging Dependencies](./epic0/0.3.1-install-logging-dependencies.md) -- See [Epic 0 README](./epic0/README.md) for remaining tasks +## Epic 2: Authentication & Authorization +- [2.1 JWT Authentication System](./epic2/2.1-jwt-authentication.md) +- [2.2 Identity Management System](./epic2/2.2-identity-management.md) +- [2.3 RBAC System](./epic2/2.3-rbac-system.md) +- [2.4 Role Management API](./epic2/2.4-role-management.md) +- [2.5 Audit Logging System](./epic2/2.5-audit-logging.md) +- [2.6 Database Seeding and Initialization](./epic2/2.6-database-seeding.md) +- [Epic 2 Overview](./epic2/README.md) -### 0.4 Basic CI/CD Pipeline -- See [Epic 0 README](./epic0/README.md) for tasks +## Epic 3: Module Framework +- [3.1 Module System Interface](./epic3/3.1-module-system-interface.md) +- [3.2 Permission Code Generation](./epic3/3.2-permission-code-generation.md) +- [3.3 Module Loader](./epic3/3.3-module-loader.md) +- [3.4 Module CLI](./epic3/3.4-module-cli.md) +- [3.5 Service Registry and Discovery](./epic3/3.5-service-registry.md) +- [Epic 3 Overview](./epic3/README.md) -### 0.5 Dependency Injection Setup -- See [Epic 0 README](./epic0/README.md) for tasks +## Epic 4: Sample Feature Module (Blog) +- [4.1 Complete Blog Module](./epic4/4.1-blog-module.md) +- [Epic 4 Overview](./epic4/README.md) -## Epic 1-8 Tasks +## Epic 5: Infrastructure Adapters +- [5.1 Cache System](./epic5/5.1-cache-system.md) +- [5.2 Event Bus](./epic5/5.2-event-bus.md) +- [5.3 Blob Storage](./epic5/5.3-blob-storage.md) +- [5.4 Email Notification](./epic5/5.4-email-notification.md) +- [5.5 Scheduler & Jobs](./epic5/5.5-scheduler-jobs.md) +- [5.6 Secret Store](./epic5/5.6-secret-store.md) +- [5.7 gRPC Service Definitions and Clients](./epic5/5.7-grpc-services.md) +- [Epic 5 Overview](./epic5/README.md) -Detailed task files for Epics 1-8 are being created. See individual epic README files: -- [Epic 1 README](./epic1/README.md) - Core Kernel & Infrastructure -- [Epic 2 README](./epic2/README.md) - Authentication & Authorization -- [Epic 3 README](./epic3/README.md) - Module Framework -- [Epic 4 README](./epic4/README.md) - Sample Feature Module (Blog) -- [Epic 5 README](./epic5/README.md) - Infrastructure Adapters -- [Epic 6 README](./epic6/README.md) - Observability & Production Readiness -- [Epic 7 README](./epic7/README.md) - Testing, Documentation & CI/CD -- [Epic 8 README](./epic8/README.md) - Advanced Features & Polish +## Epic 6: Observability & Production Readiness +- [6.1 Enhanced Observability](./epic6/6.1-enhanced-observability.md) +- [6.2 Error Reporting](./epic6/6.2-error-reporting.md) +- [6.3 Grafana Dashboards](./epic6/6.3-grafana-dashboards.md) +- [6.4 Rate Limiting](./epic6/6.4-rate-limiting.md) +- [6.5 Security Hardening](./epic6/6.5-security-hardening.md) +- [6.6 Performance Optimization](./epic6/6.6-performance-optimization.md) +- [Epic 6 Overview](./epic6/README.md) + +## Epic 7: Testing, Documentation & CI/CD +- [7.1 Testing Suite](./epic7/7.1-testing-suite.md) +- [7.2 Documentation](./epic7/7.2-documentation.md) +- [7.3 CI/CD Enhancement](./epic7/7.3-cicd-enhancement.md) +- [7.4 Docker Deployment](./epic7/7.4-docker-deployment.md) +- [Epic 7 Overview](./epic7/README.md) + +## Epic 8: Advanced Features & Polish +- [8.1 OIDC Support](./epic8/8.1-oidc-support.md) +- [8.2 GraphQL API](./epic8/8.2-graphql-api.md) +- [8.3 Additional Modules](./epic8/8.3-additional-modules.md) +- [8.4 Final Polish](./epic8/8.4-final-polish.md) +- [Epic 8 Overview](./epic8/README.md) ## Task Status Tracking diff --git a/docs/content/stories/TASK_TEMPLATE.md b/docs/content/stories/TASK_TEMPLATE.md index 65de870..9466b6d 100644 --- a/docs/content/stories/TASK_TEMPLATE.md +++ b/docs/content/stories/TASK_TEMPLATE.md @@ -31,7 +31,7 @@ Use this template for creating new task files. - [ ] {Criterion 3} ## Related ADRs -- [ADR-XXXX: {ADR Title}](../../adr/XXXX-adr-title.md) +- [ADR-XXXX: {ADR Title}](../adr/XXXX-adr-title.md) ## Implementation Notes - {Note 1} diff --git a/docs/content/stories/generate_tasks.py b/docs/content/stories/generate_tasks.py index 4f2f986..4aa6a5e 100644 --- a/docs/content/stories/generate_tasks.py +++ b/docs/content/stories/generate_tasks.py @@ -14,7 +14,7 @@ def parse_plan(plan_path): content = f.read() tasks = [] - current_phase = None + current_epic = None current_section = None subtask_num = 1 @@ -23,11 +23,12 @@ def parse_plan(plan_path): while i < len(lines): line = lines[i].rstrip() - # Phase header - phase_match = re.match(r'^## Phase (\d+):', line) - if phase_match: - current_phase = int(phase_match.group(1)) - subtask_num = 1 # Reset subtask counter for new phase + # Epic header (supports legacy Phase headers for compatibility) + epic_match = re.match(r'^## Epic (\d+):', line) + legacy_phase_match = re.match(r'^## Phase (\d+):', line) + if epic_match or legacy_phase_match: + current_epic = int((epic_match or legacy_phase_match).group(1)) + subtask_num = 1 # Reset subtask counter for new epic i += 1 continue @@ -41,7 +42,7 @@ def parse_plan(plan_path): # Task item (checkbox) - must match exactly task_match = re.match(r'^- \[ \] (.+)', line) - if task_match and current_phase is not None and current_section is not None: + if task_match and current_epic is not None and current_section is not None: task_desc = task_match.group(1).strip() # Handle tasks that end with colon (might have code block or list following) @@ -64,10 +65,10 @@ def parse_plan(plan_path): else: i += 1 - # Only add if we have valid phase and section - if current_phase is not None and current_section is not None: + # Only add if we have valid epic and section + if current_epic is not None and current_section is not None: tasks.append({ - 'phase': current_phase, + 'epic': current_epic, 'section': current_section, 'subtask': subtask_num, 'description': task_desc, @@ -82,14 +83,14 @@ def parse_plan(plan_path): def create_task_file(task, output_dir): """Create a task markdown file""" - phase_dir = output_dir / f"phase{task['phase']}" - phase_dir.mkdir(exist_ok=True) + epic_dir = output_dir / f"epic{task['epic']}" + epic_dir.mkdir(exist_ok=True) task_id = f"{task['section']}.{task['subtask']}" # Create safe filename safe_desc = re.sub(r'[^\w\s-]', '', task['description'])[:50].strip().replace(' ', '-').lower() filename = f"{task_id}-{safe_desc}.md" - filepath = phase_dir / filename + filepath = epic_dir / filename # Generate content content = f"""# Task {task_id}: {task['description']} @@ -97,7 +98,7 @@ def create_task_file(task, output_dir): ## Metadata - **Task ID**: {task_id} - **Title**: {task['description']} -- **Phase**: {task['phase']} - {get_phase_name(task['phase'])} +- **Epic**: {task['epic']} - {get_epic_name(task['epic'])} - **Section**: {task['section']} - **Status**: Pending - **Priority**: High @@ -142,9 +143,9 @@ go test ./... return filepath -def get_phase_name(phase_num): - """Get phase name from number""" - phases = { +def get_epic_name(epic_num): + """Get epic name from number""" + epics = { 0: "Project Setup & Foundation", 1: "Core Kernel & Infrastructure", 2: "Authentication & Authorization", @@ -155,7 +156,7 @@ def get_phase_name(phase_num): 7: "Testing, Documentation & CI/CD", 8: "Advanced Features & Polish" } - return phases.get(phase_num, "Unknown") + return epics.get(epic_num, "Unknown") def main(): script_dir = Path(__file__).parent @@ -182,13 +183,13 @@ def main(): task_id = f"{task['section']}.{task['subtask']}" # Determine filepath before creating - phase_dir = output_dir / f"phase{task['phase']}" - phase_dir.mkdir(exist_ok=True) + epic_dir = output_dir / f"epic{task['epic']}" + epic_dir.mkdir(exist_ok=True) # Create safe filename safe_desc = re.sub(r'[^\w\s-]', '', task['description'])[:50].strip().replace(' ', '-').lower() filename = f"{task_id}-{safe_desc}.md" - filepath = phase_dir / filename + filepath = epic_dir / filename # Check if file already exists (skip if so) if filepath.exists() and filepath.stat().st_size > 100: diff --git a/docs/content/versions.json b/docs/content/versions.json new file mode 100644 index 0000000..757484c --- /dev/null +++ b/docs/content/versions.json @@ -0,0 +1,9 @@ +[ + { + "version": "latest", + "title": "Latest", + "aliases": ["stable"], + "default": true + } +] + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index cde324a..a920c1a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -80,17 +80,17 @@ nav: - Implementation Plan: plan.md - Playbook: playbook.md - Architecture: - - Architecture Overview: architecture.md - - Module Architecture: architecture-modules.md - - Module Requirements: module-requirements.md - - Component Relationships: component-relationships.md - - System Specifications: - - System Behavior Overview: system-behavior.md - - Service Orchestration: service-orchestration.md - - Module Integration Patterns: module-integration-patterns.md - - Operational Scenarios: operational-scenarios.md - - Data Flow Patterns: data-flow-patterns.md - - Architecture Decision Records: + - Architecture Overview: architecture/architecture.md + - Module Architecture: architecture/architecture-modules.md + - Module Requirements: architecture/module-requirements.md + - Component Relationships: architecture/component-relationships.md + - System Specifications: + - System Behavior Overview: architecture/system-behavior.md + - Service Orchestration: architecture/service-orchestration.md + - Module Integration Patterns: architecture/module-integration-patterns.md + - Operational Scenarios: architecture/operational-scenarios.md + - Data Flow Patterns: architecture/data-flow-patterns.md + - Decisions: - ADR Overview: adr/README.md - "Epic 0: Project Setup & Foundation": - "ADR-0001: Go Module Path": adr/0001-go-module-path.md @@ -130,7 +130,7 @@ nav: - "Architecture & Scaling": - "ADR-0029: Microservices Architecture": adr/0029-microservices-architecture.md - "ADR-0030: Service Communication Strategy": adr/0030-service-communication-strategy.md - - Implementation Tasks: + - Implementation: - Tasks Overview: stories/README.md - "Epic 0: Project Setup & Foundation": stories/epic0/README.md - "Epic 1: Core Kernel & Infrastructure": stories/epic1/README.md @@ -153,9 +153,7 @@ extra_css: extra: social: - icon: fontawesome/brands/github - link: https://github.com/yourorg/platform - version: - provider: mike + link: https://git.dcentral.systems/toolz/goplt # Copyright copyright: Copyright © 2024 Go Platform Team