0x1d
6a17236474
- 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.
83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
# 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
|
|
|