# Project Architecture

> project-architecture

- Skill: `goldziher/project-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add goldziher/project-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldziher/project-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: goldziher (https://skillmd.com/u/goldziher)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goldziher/project-architecture

---


# Project Architecture

## Project Architecture

### Package Structure

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

```text
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:

```go
// 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:

```go
// 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:

```bash
# 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.