docs: add implementation plan, ADRs, and task tracking system
- Add comprehensive 8-phase implementation plan (docs/plan.md) - Add 28 Architecture Decision Records (docs/adr/) covering all phases - Add task tracking system with 283+ task files (docs/stories/) - Add task generator script for automated task file creation - Add reference playbooks and requirements documentation This commit establishes the complete planning foundation for the Go Platform implementation, documenting all architectural decisions and providing detailed task breakdown for Phases 0-8.
This commit is contained in:
82
docs/adr/0007-project-directory-structure.md
Normal file
82
docs/adr/0007-project-directory-structure.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# ADR-0007: Project Directory Structure
|
||||
|
||||
## Status
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
The project needs a clear, scalable directory structure that:
|
||||
- Follows Go best practices
|
||||
- Separates public interfaces from implementations
|
||||
- Supports modular architecture
|
||||
- Is maintainable and discoverable
|
||||
- Aligns with Go community standards
|
||||
|
||||
## Decision
|
||||
Adopt a **standard Go project layout** with **internal/** and **pkg/** separation:
|
||||
|
||||
```
|
||||
goplt/
|
||||
├── cmd/
|
||||
│ └── platform/ # Application entry point
|
||||
├── internal/ # Private implementation code
|
||||
│ ├── di/ # Dependency injection
|
||||
│ ├── registry/ # Module registry
|
||||
│ ├── pluginloader/ # Plugin loader (optional)
|
||||
│ ├── config/ # Config implementation
|
||||
│ ├── logger/ # Logger implementation
|
||||
│ └── infra/ # Infrastructure adapters
|
||||
├── pkg/ # Public interfaces (exported)
|
||||
│ ├── config/ # ConfigProvider interface
|
||||
│ ├── logger/ # Logger interface
|
||||
│ ├── module/ # IModule interface
|
||||
│ ├── auth/ # Auth interfaces (Phase 2)
|
||||
│ ├── perm/ # Permission DSL (Phase 2)
|
||||
│ └── infra/ # Infrastructure interfaces
|
||||
├── modules/ # Feature modules
|
||||
│ └── blog/ # Sample module (Phase 4)
|
||||
├── config/ # Configuration files
|
||||
│ ├── default.yaml
|
||||
│ ├── development.yaml
|
||||
│ └── production.yaml
|
||||
├── api/ # OpenAPI specs
|
||||
├── scripts/ # Build/test scripts
|
||||
├── docs/ # Documentation
|
||||
│ └── adr/ # Architecture Decision Records
|
||||
├── ops/ # Operations (Grafana dashboards, etc.)
|
||||
├── .github/
|
||||
│ └── workflows/
|
||||
│ └── ci.yml
|
||||
├── Dockerfile
|
||||
├── docker-compose.yml
|
||||
├── docker-compose.test.yml
|
||||
└── go.mod
|
||||
```
|
||||
|
||||
**Rationale:**
|
||||
- `internal/` prevents external packages from importing implementation details
|
||||
- `pkg/` exposes only interfaces that modules need
|
||||
- `cmd/` follows Go standard for application entry points
|
||||
- `modules/` clearly separates feature modules
|
||||
- `config/` centralizes configuration files
|
||||
- Separates concerns and supports clean architecture
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Clear separation of concerns
|
||||
- Prevents circular dependencies
|
||||
- Easy to navigate and understand
|
||||
- Aligns with Go community standards
|
||||
- Supports modular architecture
|
||||
|
||||
### Negative
|
||||
- Slightly more directories than minimal structure
|
||||
- Requires discipline to maintain boundaries
|
||||
|
||||
### Implementation Notes
|
||||
- Initialize with `go mod init git.dcentral.systems/toolz/goplt`
|
||||
- Create all directories upfront in Phase 0
|
||||
- Document structure in `README.md`
|
||||
- Enforce boundaries via `internal/` package visibility
|
||||
- Use `go build ./...` to verify structure
|
||||
|
||||
Reference in New Issue
Block a user