goplt/docs/content/stories/epic0/0.1-project-initialization.md

# Story 0.1: Project Initialization and Repository Structure

## Metadata
- **Story ID**: 0.1
- **Title**: Project Initialization and Repository Structure
- **Epic**: 0 - Project Setup & Foundation
- **Status**: Completed
- **Priority**: High
- **Estimated Time**: 2-3 hours
- **Dependencies**: None

## Goal
Establish a properly structured Go project with all necessary directories, configuration files, and documentation that follows Go best practices and supports the platform's modular architecture.

## Description
This story covers the complete project initialization, including Go module setup, directory structure creation, and initial documentation. The project structure must support the microservices architecture with clear separation between core services, feature services (modules), and infrastructure.

## Deliverables

### 1. Go Module Initialization
- Initialize Go module with correct module path: `git.dcentral.systems/toolz/goplt`
- Set Go version to 1.24 in `go.mod`
- Verify module initialization with `go mod verify`

### 2. Complete Directory Structure
Create the following directory structure:
```
platform/
├── cmd/
│   └── platform/          # Main entry point
├── internal/              # Private implementation code
│   ├── di/                # Dependency injection container
│   ├── registry/          # Module registry
│   ├── pluginloader/      # Plugin loader (optional)
│   ├── config/            # Config implementation
│   ├── logger/            # Logger implementation
│   ├── infra/             # Infrastructure adapters
│   └── ent/               # Ent ORM schemas
├── pkg/                   # Public interfaces (exported)
│   ├── config/            # ConfigProvider interface
│   ├── logger/            # Logger interface
│   ├── module/            # IModule interface
│   ├── auth/              # Auth interfaces
│   ├── perm/              # Permission DSL
│   └── infra/             # Infrastructure interfaces
├── modules/               # Feature modules
│   └── blog/              # Sample Blog module (Epic 4)
├── config/                # Configuration files
│   ├── default.yaml
│   ├── development.yaml
│   └── production.yaml
├── api/                   # OpenAPI specs
├── scripts/               # Build/test scripts
├── docs/                  # Documentation
├── ops/                   # Operations (Grafana dashboards, etc.)
├── .github/
│   └── workflows/
│       └── ci.yml
├── Dockerfile
├── docker-compose.yml
├── docker-compose.test.yml
├── .gitignore
├── README.md
└── go.mod
```

### 3. .gitignore Configuration
- Exclude build artifacts (`bin/`, `dist/`)
- Exclude Go build cache
- Exclude IDE files (`.vscode/`, `.idea/`, etc.)
- Exclude test coverage files
- Exclude dependency directories
- Exclude environment-specific files

### 4. Initial README.md
Create comprehensive README with:
- Project overview and purpose
- Architecture overview
- Quick start guide
- Development setup instructions
- Directory structure explanation
- Links to documentation
- Contributing guidelines

### 5. Basic Documentation Structure
- Set up `docs/` directory
- Create architecture documentation placeholder
- Create API documentation structure

## Implementation Steps

1. **Initialize Go Module**
   ```bash
   go mod init git.dcentral.systems/toolz/goplt
   ```
   - Verify `go.mod` is created
   - Set Go version constraint

2. **Create Directory Structure**
   - Create all directories listed above
   - Ensure proper nesting and organization
   - Add placeholder `.gitkeep` files in empty directories if needed

3. **Configure .gitignore**
   - Add Go-specific ignore patterns
   - Add IDE-specific patterns
   - Add OS-specific patterns
   - Add build artifact patterns

4. **Create README.md**
   - Write comprehensive project overview
   - Document architecture principles
   - Provide setup instructions
   - Include example commands

5. **Verify Structure**
   - Run `go mod verify`
   - Check all directories exist
   - Verify .gitignore works
   - Test README formatting

## Acceptance Criteria
- [x] `go mod init` creates module with correct path `git.dcentral.systems/toolz/goplt`
- [x] Go version is set to `1.24` in `go.mod`
- [x] All directories from the structure are in place
- [x] `.gitignore` excludes build artifacts, dependencies, and IDE files
- [x] `README.md` provides clear project overview and setup instructions
- [x] Project structure matches architecture documentation
- [x] `go mod verify` passes
- [x] Directory structure follows Go best practices

## Related ADRs
- [ADR-0001: Go Module Path](../../adr/0001-go-module-path.md)
- [ADR-0002: Go Version](../../adr/0002-go-version.md)
- [ADR-0007: Project Directory Structure](../../adr/0007-project-directory-structure.md)

## Implementation Notes
- The module path should match the organization's Git hosting structure
- All internal packages must use `internal/` prefix to ensure they are not importable by external modules
- Public interfaces in `pkg/` should be minimal and well-documented
- Empty directories can have `.gitkeep` files to ensure they are tracked in Git
- The directory structure should be documented in the README

## Testing
```bash
# Verify module initialization
go mod verify
go mod tidy

# Check directory structure
tree -L 3 -a

# Verify .gitignore
git status
```

## Files to Create/Modify
- `go.mod` - Go module definition
- `README.md` - Project documentation
- `.gitignore` - Git ignore patterns
- All directory structure as listed above