goplt/AGENTS.md

# Agent Instructions for Go Platform Project

This document provides essential guidance for AI agents and developers working on the Go Platform project. **Always consult the documentation before making changes or implementing features.**

## 🚨 Critical Requirement

**BEFORE making any code changes, architectural decisions, or implementing features, you MUST:**

1. ✅ Review relevant **documentation** files
2. ✅ Check applicable **architecture** documents
3. ✅ Consult relevant **Architecture Decision Records (ADRs)**
4. ✅ Review the **stories** (epic-based implementation tasks)

Failure to follow these guidelines may result in code that doesn't align with the project's architecture, principles, or implementation plan.

---

## 📚 Documentation Structure

All documentation is located in `/goplt/docs/content/`. The project follows a structured documentation approach:

### Core Documentation (`/goplt/docs/content/`)

- **`index.md`**: Main documentation index and navigation
- **`requirements.md`**: High-level architectural principles and requirements
- **`plan.md`**: Epic-based implementation plan with timelines and acceptance criteria
- **`playbook.md`**: Detailed implementation guide, best practices, and technical specifications

### Architecture Documentation (`/goplt/docs/content/architecture/`)

- **`architecture.md`**: System architecture overview with diagrams
- **`architecture-modules.md`**: Module system design and integration patterns
- **`module-requirements.md`**: Detailed requirements for each module
- **`component-relationships.md`**: Component interactions and dependencies
- **`system-behavior.md`**: System behavior overview end-to-end
- **`service-orchestration.md`**: How services work together
- **`module-integration-patterns.md`**: How modules integrate with the platform
- **`operational-scenarios.md`**: Common operational flows and use cases
- **`data-flow-patterns.md`**: How data flows through the system

### Architecture Decision Records (`/goplt/docs/content/adr/`)

All architectural decisions are documented in ADR files (ADR-0001 through ADR-0030+). These records explain:
- The context that led to the decision
- The decision itself
- The rationale and consequences
- Implementation notes

**Key ADRs to review:**
- ADR-0001: Go Module Path
- ADR-0003: Dependency Injection Framework
- ADR-0004: Configuration Management
- ADR-0005: Logging Framework
- ADR-0006: HTTP Framework
- ADR-0007: Project Directory Structure
- ADR-0008: Error Handling Strategy
- ADR-0013: Database ORM
- ADR-0016: OpenTelemetry Observability
- ADR-0017: JWT Token Strategy
- ADR-0021: Module Loading Strategy
- ADR-0022: Cache Implementation
- ADR-0023: Event Bus Implementation
- ADR-0025: Multitenancy Model
- ADR-0027: Rate Limiting Strategy
- ADR-0028: Testing Strategy
- ADR-0029: Microservices Architecture
- ADR-0030: Service Communication Strategy

**Always check ADRs before making architectural decisions!**

### Implementation Stories (`/goplt/docs/content/stories/`)

The project is organized into **8 epics**, each containing specific implementation stories:

- **Epic 0**: Project Setup & Foundation (`epic0/`)
  - 0.1: Project Initialization
  - 0.2: Configuration Management System
  - 0.3: Structured Logging System
  - 0.4: CI/CD Pipeline
  - 0.5: Dependency Injection and Bootstrap

- **Epic 1**: Core Kernel & Infrastructure (`epic1/`)
  - 1.1: Enhanced DI Container
  - 1.2: Database Layer
  - 1.3: Health & Metrics System
  - 1.4: Error Handling
  - 1.5: HTTP Server
  - 1.6: OpenTelemetry
  - 1.7: Service Abstraction Layer

- **Epic 2**: Authentication & Authorization (`epic2/`)
  - 2.1: JWT Authentication
  - 2.2: Identity Management
  - 2.3: RBAC System
  - 2.4: Role Management
  - 2.5: Audit Logging
  - 2.6: Database Seeding

- **Epic 3**: Module Framework (`epic3/`)
  - 3.1: Module System Interface
  - 3.2: Permission Code Generation
  - 3.3: Module Loader
  - 3.4: Module CLI
  - 3.5: Service Registry

- **Epic 4**: Sample Feature Module (`epic4/`)
  - 4.1: Blog Module

- **Epic 5**: Infrastructure Adapters (`epic5/`)
  - 5.1: Cache System
  - 5.2: Event Bus
  - 5.3: Blob Storage
  - 5.4: Email Notification
  - 5.5: Scheduler Jobs
  - 5.6: Secret Store
  - 5.7: gRPC Services

- **Epic 6**: Observability & Production Readiness (`epic6/`)
  - 6.1: Enhanced Observability
  - 6.2: Error Reporting
  - 6.3: Grafana Dashboards
  - 6.4: Rate Limiting
  - 6.5: Security Hardening
  - 6.6: Performance Optimization

- **Epic 7**: Testing, Documentation & CI/CD (`epic7/`)
  - 7.1: Testing Suite
  - 7.2: Documentation
  - 7.3: CI/CD Enhancement
  - 7.4: Docker Deployment

- **Epic 8**: Advanced Features & Polish (`epic8/`)

Each story file contains:
- **Goal**: What needs to be accomplished
- **Deliverables**: Specific items to be created
- **Acceptance Criteria**: How to verify completion
- **Implementation Notes**: Technical guidance

**Always review the relevant story before implementing a feature!**

---

## 🔍 Workflow for Agents

When working on this project, follow this workflow:

### 0. Git Workflow (MANDATORY)
- **ALWAYS create a new branch** when working on a new feature, bug fix, or enhancement
  - Use descriptive branch names (e.g., `feature/epic1-http-server`, `bugfix/auth-token-expiry`, `enhancement/rate-limiting`)
  - Branch names should follow the pattern: `{type}/{epic}-{short-description}` or `{type}/{story-id}-{short-description}`
- **ALWAYS create a commit** after successfully implementing a feature that:
  - ✅ Builds successfully (`go build` passes)
  - ✅ Tests pass (`go test` passes)
  - ✅ Meets all acceptance criteria from the story
- Commit messages should be clear and descriptive, referencing the story/epic when applicable
- Never commit directly to `main` branch

### 1. Understand the Task
- Read the user's request carefully
- Identify which epic/story the task relates to
- Determine if it's a new feature, bug fix, or enhancement

### 2. Consult Documentation (MANDATORY)
- **Start with `index.md`** to get oriented
- **Read the relevant story** from `/goplt/docs/content/stories/epicX/`
- **Review architecture documents** that relate to the feature
- **Check ADRs** for any architectural decisions that apply
- **Review `playbook.md`** for implementation patterns and best practices

### 3. Understand the Architecture
- Review the **architecture overview** (`architecture/architecture.md`)
- Check **component relationships** if integrating with existing systems
- Review **module integration patterns** if working on modules
- Understand **data flow patterns** if working on data processing

### 4. Check ADRs
- Search for ADRs related to your task
- Ensure your implementation aligns with documented decisions
- If you need to make a new architectural decision, document it in a new ADR

### 5. Implement According to Stories
- Follow the deliverables specified in the story
- Meet the acceptance criteria
- Use the implementation notes as guidance
- Follow the patterns established in `playbook.md`

### 6. Verify Alignment
- Ensure code follows Clean/Hexagonal Architecture principles
- Verify it aligns with microservices architecture
- Check that it follows plugin-first design
- Confirm security-by-design principles are followed
- Validate observability is properly implemented

### 7. Commit Changes
- **ALWAYS commit** after successful implementation
- Ensure the code builds (`go build`)
- Ensure all tests pass (`go test`)
- Verify all acceptance criteria are met
- Write a clear, descriptive commit message

---

## 🏗️ Key Architectural Principles

The project follows these core principles (documented in `requirements.md` and `playbook.md`):

1. **Clean/Hexagonal Architecture**
   - Clear separation between `pkg/` (interfaces) and `internal/` (implementations)
   - Domain code in `internal/domain`
   - Only interfaces exported from `pkg/`

2. **Microservices Architecture**
   - Each module is an independent service from day one
   - Services communicate via gRPC/HTTP
   - Service discovery via service registry

3. **Plugin-First Design**
   - Extensible architecture supporting static and dynamic modules
   - Modules implement the `IModule` interface
   - Module loader discovers and loads modules

4. **Security-by-Design**
   - JWT authentication
   - RBAC/ABAC authorization
   - Audit logging
   - Context-based user propagation

5. **Observability**
   - OpenTelemetry integration
   - Structured logging (Zap)
   - Prometheus metrics
   - Request correlation IDs

6. **Dependency Injection**
   - Using `uber-go/fx` for lifecycle management
   - Constructor injection preferred
   - Service registry pattern

---

## 📋 Quick Reference Checklist

Before implementing any feature, verify:

- [ ] Created a new branch for the feature/bugfix/enhancement
- [ ] Read the relevant story from `/goplt/docs/content/stories/epicX/`
- [ ] Reviewed architecture documents in `/goplt/docs/content/architecture/`
- [ ] Checked applicable ADRs in `/goplt/docs/content/adr/`
- [ ] Consulted `playbook.md` for implementation patterns
- [ ] Understood the epic context and dependencies
- [ ] Verified acceptance criteria are clear
- [ ] Confirmed architectural alignment

After implementing a feature, verify:

- [ ] Code builds successfully (`go build`)
- [ ] All tests pass (`go test`)
- [ ] All acceptance criteria are met
- [ ] Created a commit with a clear, descriptive message

---

## 🚫 Common Mistakes to Avoid

1. **Working directly on main branch** - Always create a feature branch before making changes
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
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
9. **Breaking microservices boundaries** - Services must communicate via defined interfaces

---

## 📖 Additional Resources

- **MkDocs Configuration**: `/goplt/docs/mkdocs.yml` - Documentation site configuration
- **Docker Setup**: `/goplt/docs/Dockerfile` and `docker-compose.yml` - Development environment
- **Makefile**: `/goplt/Makefile` - Build and development commands
- **Story Generator**: `/goplt/docs/content/stories/generate_tasks.py` - Tool for generating story templates

---

## 💡 Tips for Agents

1. **Use semantic search** to find relevant documentation when you're unsure
2. **Read multiple related files** to get complete context
3. **Check the epic README files** (`epicX/README.md`) for epic-level overviews
4. **Review `COMPLETE_TASK_LIST.md`** for a comprehensive task overview
5. **When in doubt, ask for clarification** rather than making assumptions

---

## 📝 Documentation Updates

If you make architectural decisions or significant changes:
1. Update relevant ADRs or create new ones
2. Update architecture documents if structure changes
3. Update stories if implementation details change
4. Keep documentation in sync with code

---

**Remember: Documentation is the source of truth. Always consult it before making changes!**