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

   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

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

Related ADRs

• ADR-0001: Go Module Path
• ADR-0002: Go Version
• ADR-0007: Project Directory Structure

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

# 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