goplt/docs/content/adr/0007-project-directory-structure.md

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