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