Add Entity and Routes

Add a new entity with complete CRUD operations to an existing feature.

When to Use

Use this when:

• Adding new data entity to existing feature
• Need full CRUD infrastructure (Create, Read, Update, Delete, List)
• Example: Add profile entity to user_management feature

Don't use when:

• Creating new feature → Use /venturo-go:new-feature
• Adding lightweight endpoint only → Use /venturo-go:add-endpoint

Workflow

Interactive Discovery

Ask these questions:

1. Which feature? (List from features/ directory)
2. Entity name? (singular, e.g., product, order, profile)
3. Database table name? (usually plural)
4. Table exists? (Yes = generate from schema, No = design schema)
5. Entity fields? (if designing new schema)
6. Relationships? (foreign keys, joins)
7. HTTP operations? (CRUD, batch, custom actions)
8. Base URL path? (e.g., /products, /orders)
9. Authentication? (public, authenticated, role-based, permission-based)
10. Business rules? (validation, state transitions, side effects)
11. External services? (email, storage, notifications)

Present plan and ask for confirmation.

Implementation Phases

Execute these 9 phases in order:

1. Migration - phases/new-entity/01-migration.md
2. Domain Entity - phases/new-entity/02-domain-entity.md
3. DTOs - phases/new-entity/03-dtos.md
4. Repository - phases/new-entity/04-repository.md
5. Service - phases/new-entity/05-service.md
6. HTTP Handler - phases/new-entity/06-handler.md
7. Routes & Errors - phases/new-entity/07-routes.md
8. Code Quality - phases/shared/code-quality.md
9. Documentation - phases/shared/documentation.md

Common Patterns

Simple CRUD Entity:

• Basic create, read, update, delete
• Example: Product, Category, Tag

Entity with Relationships:

• References other entities
• Example: Order (belongs to User)

Entity with State Machine:

• Status transitions + business rules
• Example: Order (draft → pending → confirmed → shipped)

Entity with Soft Delete:

• Uses GORM DeletedAt field
• Never permanently deleted

Entity with Audit Trail:

• Tracks CreatedBy, UpdatedBy
• Populated from auth context

File Naming Conventions

• Entities: entity.{entity}.go (singular)
• DTOs: request.{entity}.go, response.{entity}.go
• Handlers: http.{entity}.go
• Repositories: repo.{entity}.go
• Services: service.{entity}.go
• Errors: errors.{feature}.go (shared)

Example

User: /venturo-go:add-entity

Claude: Which feature?
- user_management
- email_sender

User: user_management

Claude: Entity name? (singular)

User: profile

Claude: Database table name?

User: user_profiles

Claude: Does table exist?

User: No

Claude: What fields?

User:
- bio: text
- avatar_url: string
- phone: string, unique
- user_id: uuid, foreign key

[Presents plan, proceeds with phases]

Tips

• Start with database schema design
• Use code generation for standard CRUD: make gen-crud
• Follow naming conventions strictly
• Add validation tags to DTOs
• Use feature-specific errors
• Test incrementally
• Add database indexes for performance
• Apply proper authentication