epic-ent/AGENTS.md

AGENTS.md

Project Overview

• This repository is a Go service named epic-ent.
• The application uses go.uber.org/fx for dependency injection and lifecycle management.
• HTTP is served with github.com/labstack/echo/v4.
• Configuration is loaded by viper from application.yaml in the repository root.
• Persistence uses MySQL plus ent ORM/codegen; Redis and cron infrastructure are also wired in.

High-Value Architecture Notes

• Main entrypoint: cmd/server/main.go
• App composition root: internal/bootstrap/app.go
• Config loading: internal/config/config.go
• HTTP server bootstrap: internal/infra/http/http.go
• Ent client bootstrap: internal/infra/db/ent.go
• Shared response envelope: internal/domain/vo/response.go

Current dependency flow follows this pattern:

1. controller handles HTTP binding and response shaping.
2. service contains business defaults/orchestration.
3. repository talks to ent and database models.
4. infra provides framework/runtime dependencies.

For feature work, preserve this layering unless the user explicitly asks for a refactor.

Directory Guide

• cmd/server: production app entrypoint.
• cmd/gen/controllers: generator for internal/controller/module.go.
• db/schema.sql: database schema reference.
• internal/bootstrap: top-level Fx wiring.
• internal/config: configuration structs and module wiring.
• internal/controller: Echo handlers and route registration.
• internal/domain/dto: request DTOs.
• internal/domain/vo: response/output view objects.
• internal/domain/entity: domain entity definitions related to schema.
• internal/repository: data access using ent.Client.
• internal/service: business service layer.
• internal/infra: logger, DB, Redis, HTTP, cron providers.
• internal/ent: generated Ent ORM code.

Generated Code Rules

• Treat internal/ent/** as generated code unless the user explicitly requests regeneration-related work.
• Do not hand-edit generated Ent files as a first choice.
• internal/controller/module.go is generated by cmd/gen/controllers/main.go.
• If controller constructors change, prefer regenerating internal/controller/module.go through the generator instead of manually maintaining it.

Editing Rules For Codex

• Keep changes minimal and consistent with existing Go style.
• Prefer extending existing controller -> service -> repository patterns over introducing new abstractions.
• Reuse existing response helpers such as vo.OK(...) and related error handling patterns.
• When adding HTTP endpoints, update route registration in internal/controller/routes.go and keep handler behavior aligned with current Echo patterns.
• When changing persistence behavior, inspect corresponding DTO/VO/repository/service flow together to avoid partial changes.
• Avoid broad refactors unless they are required to solve the requested task.

Config And Secrets

• application.yaml currently contains real-looking database and Redis credentials.
• Do not print, duplicate, or move those secrets into additional files.
• If config changes are required, prefer structure-preserving edits and avoid exposing credential values in summaries.
• If the user asks for security hardening, a strong candidate improvement is migrating secrets out of the committed config and into environment variables or untracked local config.

Known Runtime Conventions

• The HTTP server port and read/write timeouts come from application.yaml.
• The server is started through Fx lifecycle hooks, not directly in main.
• Repository methods use soft delete semantics for heroes via deleted = false/true filtering and updates.
• Current API examples in internal/controller expose CRUD-style /heroes routes.

Validation Guidance

When verifying changes, prefer the smallest useful command first:

• go test ./...
• go build ./cmd/server
• If generator-related files changed, also run the relevant generator command before testing.

Run validation from the repository root: epic-ent.

Safe Default Workflow

1. Read the affected entrypoint/module/wiring before editing.
2. Check whether the target file is generated.
3. Make focused changes in the appropriate layer.
4. Validate with targeted go test or go build when feasible.
5. Summarize changed files and any remaining risks.

Current Observations

• The repository appears to focus on Epic Seven-related data entities, with hero currently being the clearest implemented end-to-end example.
• There may be more entities already represented in internal/ent and internal/domain/entity than are currently exposed via controllers/services.
• Because Ent code is already generated for multiple tables, schema-driven changes may require coordinated updates rather than isolated handler edits.