# 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