project-architecture

description	project-architecture
name	project-architecture
user_invocable	false

Project Architecture

Project Architecture

Package Structure

go-utils is organized into specialized utility packages, each focused on a specific data type:

go-utils/
├── dateutils/      # Time and date manipulation utilities
├── maputils/       # Generic map operations
├── sliceutils/     # Generic slice operations (inspired by JS Array methods)
├── stringutils/    # String manipulation and formatting
├── structutils/    # Struct reflection and conversion utilities
└── urlutils/       # URL and query string utilities

Design Principles

1. Generics-First Approach

All functions leverage Go 1.18+ generics for type safety:

// Example: sliceutils.Filter signature
func Filter[T any](slice []T, predicate func(value T, index int, slice []T) bool) []T

// Example: maputils.Keys signature
func Keys[K comparable, V any](mapInstance map[K]V) []K

2. Functional Programming Style

Many functions accept callback functions with consistent signatures:

// Slice callbacks receive: value, index, slice
sliceutils.Map(items, func(value T, index int, slice []T) R { ... })

// Map callbacks receive: key, value
maputils.ForEach(m, func(key K, value V) { ... })

3. Zero-Cost Abstractions

Functions are designed for performance with minimal overhead:

• Pre-allocated slices where sizes are known
• In-place operations where appropriate
• Efficient iteration patterns

Adding New Utilities

When contributing a new utility function:

1. Choose the correct package based on the primary data type
2. Add the function to <package>/<package>.go
3. Add comprehensive tests to <package>/<package>_test.go
4. Create documentation at docs/<package>/<function>.md following existing patterns
5. Update mkdocs.yml to include the new documentation page

Documentation Generation

Documentation is built with MkDocs and deployed automatically:

# Install MkDocs (if not already installed)
pip install mkdocs mkdocs-material

# Serve documentation locally
mkdocs serve
# Visit http://127.0.0.1:8000

# Build static documentation
mkdocs build

Documentation structure in mkdocs.yml mirrors the package structure for easy navigation.