# Lokstra Overview

> Provides foundational understanding of Lokstra Framework architecture, design principles, annotation-based code generation, and decision-making guidelines for AI agents building Go web applications. Use when starting any Lokstra project or when agents need framework context.

- Skill: `tomevault-io/lokstra-overview` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/lokstra-overview`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lokstra-overview/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/lokstra-overview

---


# Lokstra Framework - Overview & Philosophy

## When to use this skill

Use this skill when:
- Starting any new Lokstra project with AI agents
- Need to understand overall framework philosophy
- Understanding 2-phase workflow: Design → Implementation
- Determining module structure (DDD bounded contexts)
- Need high-level architecture guidance

## Framework Overview

Lokstra is a **Go web framework** with:
- Design-first development approach (BRD → Code)
- Annotation-based code generation
- Full dependency injection framework
- Modular architecture using DDD bounded contexts
- Auto-code generation for routes, services, dependencies

**Two Main Phases:**

### Phase 1: Design (Using Design Skills)
```
BRD → Module Requirements → API Spec → Database Schema
```
- Focus on planning, requirements, and specifications
- Human-readable documents for stakeholder approval
- No code written yet

### Phase 2: Implementation (Using Implementation Skills)
```
Initialize Framework → Config → Handlers → Services → Migrations → Tests
```
- Focus on code generation based on design phase
- Microskills for each implementation concern
- Annotation-based code (minimal boilerplate)

---

## Development Workflow

**Design Phase → Implementation Phase:**

```
1. lokstra-overview (framework fundamentals)
   ↓
2. lokstra-brd-generation (define business requirements)
   ↓
3. lokstra-module-requirements (break into modules)
   ↓
4. lokstra-api-specification (define API endpoints)
   ↓
5. lokstra-schema-design (define database schema)
   ↓
   SPECIFICATIONS READY
   ↓
6. implementation-lokstra-init-framework (initialize)
7. implementation-lokstra-yaml-config (config)
8. implementation-lokstra-create-handler (@Handler)
9. implementation-lokstra-create-service (@Service)
10. implementation-lokstra-create-migrations (migrations)
11. implementation-lokstra-generate-http-files (HTTP client)
    ↓
    CODE READY
    ↓
12. advanced-lokstra-tests (testing)
13. advanced-lokstra-middleware (custom middleware)
14. advanced-lokstra-validate-consistency (validation)
```

**Migrations note:** Apply migrations explicitly with `lokstra migration up` (not auto-run). If `migration.yaml` exists in a folder, it supplies `dbpool-name` / optional `schema-table` / optional `enabled: false`; otherwise use `-db` to pick the pool.

## Core Design Philosophy

### 1. Document-Driven Development

**Problem:** Code-first approaches lead to rework, inconsistencies, technical debt.

**Solution:** Design-first workflow (specs before code):
- Clear stakeholder alignment
- Built-in compliance documentation
- Eliminates "code-then-fix" cycles
- Estimated 10x productivity improvement

### 2. Bounded Context (DDD)

**Module Granularity:**
- ❌ Wrong: One `user` module handling auth + profile + notifications
- ✅ Right: Separate `auth`, `user_profile`, `notification` modules

**Benefits:** Independent scaling, clear responsibilities, easier testing

### 3. Project Structure Consistency

All Lokstra projects follow same structure (simple → enterprise):

```
myapp/
├── .github/skills/              # AI Agent instructions
├── configs/                     # YAML config files (auto-merged)
│   ├── config.yaml
│   ├── database-config.yaml
│   └── <module-name>-config.yaml
├── migrations/                  # Database migrations per module
│   ├── shared/
│   └── <module_name>/
├── docs/
│   ├── drafts/                  # BRD/requirements drafts
│   └── modules/                 # Published specs
└── modules/
    ├── shared/domain/           # Cross-module models
    └── <module_name>/
        ├── handler/             # @Handler (1 per entity)
        ├── repository/          # Data access (1 per entity)
        └── domain/              # Business logic & DTOs
```

**Rules:**
- Multi-file YAML config in `/configs/` - auto-merged
- Migrations by module in `/migrations/{module}/`
- 1 handler per entity (not `handlers.go` with 10+ entities)
- DTOs with validation tags in domain layer

---

## Annotations & Code Generation

**Why Annotations?**
- Reduce boilerplate code
- Type-safe at compile time
- Clear service dependencies
- Auto-generates routing, DI, service registration

**Core Annotations:**
- `@Handler` - Business service with routes
- `@Service` - Infrastructure service
- `@Route` - HTTP endpoint mapping
- `@Inject` - Dependency injection

**Code Details:** See implementation-phase skills for specific syntax

---

## Cross-Module Communication

**Pattern:** Via dependency injection (not direct calls)

**Shared Models:** `/modules/shared/domain/`

**Async Operations:** Event-driven for loose coupling

**Details:** See design-lokstra-module-requirements for integration points

---

## Configuration Management

**Multi-file YAML:**
- All files in `/configs/` auto-merged
- Environment variables supported (${VAR:default})
- Service definitions with dependencies
- Deployment configurations

**Details:** See implementation-lokstra-yaml-config skill

---

## Best Practices Summary

- ✅ Design first, code second
- ✅ Document-driven development
- ✅ DDD bounded contexts (separate modules)
- ✅ 1 file per entity
- ✅ Annotations over manual code
- ✅ Type-safe dependency injection
- ✅ Validation tags on DTOs
```

---

## Next Steps

After understanding the framework overview:

### DESIGN PHASE (Specifications)

1. **[design-lokstra-brd-generation](../design-lokstra-brd-generation/SKILL.md)**
   - Create Business Requirements Document
   - Define stakeholder requirements, user stories, acceptance criteria

2. **[design-lokstra-module-requirements](../design-lokstra-module-requirements/SKILL.md)**
   - Break BRD into modules (Bounded Contexts using DDD)
   - Define module responsibilities and integration points

3. **[design-lokstra-api-specification](../design-lokstra-api-specification/SKILL.md)**
   - Design API endpoints, request/response schemas
   - Create endpoint specs with validation rules and examples

4. **[design-lokstra-schema-design](../design-lokstra-schema-design/SKILL.md)**
   - Design database schema with tables, indexes, constraints
   - Create migration files (UP/DOWN SQL)

### IMPLEMENTATION PHASE (Code Generation)

5. **[implementation-lokstra-init-framework](../implementation-lokstra-init-framework/SKILL.md)**
   - Initialize main.go with lokstra.Bootstrap()
   - Register services and middleware

6. **[implementation-lokstra-yaml-config](../implementation-lokstra-yaml-config/SKILL.md)**
   - Create multi-file YAML configuration
   - Set up service definitions and deployments

7. **[implementation-lokstra-create-handler](../implementation-lokstra-create-handler/SKILL.md)**
   - Create @Handler annotated endpoints
   - Implement @Route decorators with request/response handling

8. **[implementation-lokstra-create-service](../implementation-lokstra-create-service/SKILL.md)**
   - Create @Service repository implementations
   - Implement data access layer

9. **[implementation-lokstra-create-migrations](../implementation-lokstra-create-migrations/SKILL.md)**
   - Create database migration files
   - Generate UP/DOWN SQL from schema design

10. **[implementation-lokstra-generate-http-files](../implementation-lokstra-generate-http-files/SKILL.md)**
    - Create .http client files for testing
    - Generate REST examples with environment variables

### ADVANCED PHASE (Testing & Validation)

11. **[advanced-lokstra-tests](../advanced-lokstra-tests/SKILL.md)**
    - Write unit tests for handlers and services
    - Create integration tests with test database

12. **[advanced-lokstra-middleware](../advanced-lokstra-middleware/SKILL.md)**
    - Implement custom middleware (auth, logging, rate limiting)
    - Add cross-cutting concerns

13. **[advanced-lokstra-validate-consistency](../advanced-lokstra-validate-consistency/SKILL.md)**
    - Validate circular dependencies
    - Check configuration completeness
    - Pre-deployment validation

---

## Key Principles

**1. Design First, Code Second**
- Always create specifications before implementation
- Clear requirements prevent rework

**2. Document-Driven Development**
- Use BRD → Requirements → Specs as single source of truth
- Generated code directly maps to specifications

**3. Bounded Contexts (DDD)**
- Each module is independent and self-contained
- Clear interfaces between modules
- Easier to test and deploy

**4. Type-Safe Dependency Injection**
- Compile-time verification of dependencies
- Configuration-based service selection
- No runtime surprises

**5. Annotation-Based Code Generation**
- Minimize boilerplate code
- Auto-generated routing and service registration
- Consistent code patterns

---

## When to Choose Lokstra

### ✅ Use Lokstra When

- Building production applications (2+ entities/modules)
- Team size: 2-50 developers
- Complexity: Medium to high (multiple services)
- Scale: Growing from MVP to enterprise
- Need: Strong type safety and structured DI

### ❌ Consider Alternatives When

- Single-file scripts or prototypes
- Learning Go fundamentals
- Very simple APIs (<5 endpoints)
- Extreme performance requirements (1M+ requests/sec)

---

## Framework Comparison

| Aspect | Lokstra | Echo | Gin | Spring Boot |
|--------|---------|------|-----|------------|
| **Language** | Go | Go | Go | Java |
| **DI** | Full Framework | Optional | Optional | Built-in |
| **Code Gen** | Annotations ✅ | Manual | Manual | Annotations |
| **Type Safety** | Excellent | Good | Good | Good |
| **Learning Curve** | Moderate | Easy | Easy | Steep |
| **Enterprise Ready** | ✅ | Good | Good | ✅ |

---

## Common Questions

**Q: Do I need to use all 14 skills?**  
A: For a typical project: Yes. Design phase → Implementation phase → Advanced phase. Optional: Skip advanced if no tests needed.

**Q: Can I skip the design phase?**  
A: Not recommended. Design phase prevents implementation errors. Estimated 10x productivity gain.

**Q: How long does a complete project take?**  
A: Small module: 4-6 hours. Medium module: 1-2 days. Large module: 3-5 days.

**Q: Do I need to use all 6 implementation skills?**  
A: Yes. They're sequential: init → config → handlers → services → migrations → tests.

**Q: Can multiple teams work in parallel?**  
A: Yes. After design phase, each team works on separate modules (bounded contexts).

---

## Summary

Lokstra Framework combines:
- ✅ **Strong typing** from Go
- ✅ **Elegant architecture** from Spring Boot/NestJS
- ✅ **Rapid development** from annotation-based code generation
- ✅ **Production readiness** from dependency injection and modular design

With the 14 AI skills, you can go from business requirement to production-ready application in days instead of weeks. 

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/primadi) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->