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 (Epic 2)
|
|
│ ├── perm/ # Permission DSL (Epic 2)
|
|
│ └── infra/ # Infrastructure interfaces
|
|
├── modules/ # Feature modules
|
|
│ └── blog/ # Sample module (Epic 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 Epic 0
|
|
- Document structure in `README.md`
|
|
- Enforce boundaries via `internal/` package visibility
|
|
- Use `go build ./...` to verify structure
|
|
|