Skip to content

AGENTS.md

Latest commit

 

History

History
93 lines (69 loc) · 4.93 KB

AGENTS.md

File metadata and controls

93 lines (69 loc) · 4.93 KB
Raw

AGENTS.md

Project Overview

This repository contains a Java 21 + Spring Boot 3 application that consumes the official Cartola FC API and exposes:

  • REST endpoints under the local Spring Boot app
  • Swagger/OpenAPI documentation
  • a static frontend served from src/main/resources/static/

The application acts as an integration layer over https://api.cartola.globo.com, so reliability, null-safety, and predictable error handling matter more than clever abstractions.

Repository Map

  • src/main/java/com/api/cartolafc/config/: Spring configuration such as RestTemplate
  • src/main/java/com/api/cartolafc/controllers/: REST controllers with ResponseEntity and OpenAPI annotations
  • src/main/java/com/api/cartolafc/services/: integration logic and business rules
  • src/main/java/com/api/cartolafc/dtos/: JSON mapping records
  • src/main/java/com/api/cartolafc/utils/: shared helpers such as BASE_URL, rounding, slug normalization, and request headers
  • src/main/resources/static/: static UI assets
  • src/test/java/com/api/cartolafc/: unit tests
  • docs/explanation/: architecture and frontend notes

Core Conventions

  • Prefer small, localized changes that fit the existing package structure.
  • Keep HTTP integration logic inside services. Do not duplicate external API calls in controllers.
  • Prefer constructor injection, matching the current codebase style.
  • Use Java record types for DTOs that model JSON payloads.
  • When mapping snake_case JSON fields, continue using @JsonProperty.
  • Keep controller responses explicit with ResponseEntity and preserve current status code behavior unless the change intentionally revises the contract.
  • Maintain or extend OpenAPI annotations when adding or changing public endpoints.

Cartola API Rules

  • Reuse Utils.BASE_URL for Cartola endpoints instead of hardcoding the base URL elsewhere.
  • Preserve the User-Agent header convention via Utils.createHttpEntityWithUserAgent() when adding new outbound calls.
  • Treat external payloads as unstable: guard against null, missing fields, invalid date strings, and unexpected fallback responses.
  • If an endpoint depends on round-specific data, validate that the returned round matches the requested round before using it.
  • Keep shield URL cleanup behavior consistent when returning team data.

Build And Run

  • Start locally: ./mvnw spring-boot:run
  • Run the full test suite: ./mvnw test
  • Run one test class: ./mvnw -Dtest=TeamsServiceTest test
  • Build the jar: ./mvnw clean package
  • Run with containers: docker compose up --build

Useful local URLs after startup:

  • App/UI: http://localhost:8080/
  • Swagger UI: http://localhost:8080/swagger-ui/index.html
  • OpenAPI JSON: http://localhost:8080/v3/api-docs
  • Healthcheck: http://localhost:8080/actuator/health

Testing Guidance

  • Prefer deterministic unit tests with Mockito over live calls to the Cartola API.
  • Add or update tests whenever business logic changes, especially in services.
  • For date-sensitive logic, avoid brittle assertions that depend on the current wall clock unless the code already follows that pattern and the test remains stable.
  • When changing monthly score logic, cover at least:
    • only finished rounds count
    • only rounds in the current month count
    • invalid or missing dates are ignored safely
    • mismatched fallback rounds are ignored
  • If JSON fixtures help readability, place them under src/test/resources/fixtures/.

Frontend Guidance

  • The frontend is intentionally simple and static. Keep it lightweight.
  • Prefer changing src/main/resources/static/js/ and src/main/resources/static/css/ instead of introducing a new frontend toolchain.
  • src/main/resources/static/data/times.csv is developer-local input and is gitignored. Do not rely on committing changes to it unless explicitly requested.
  • Keep the frontend compatible with the backend running on the same origin by default.

Documentation Guidance

  • If you change endpoint behavior, update README.md and relevant OpenAPI annotations.
  • If you change architecture or the static UI flow in a meaningful way, update the matching file in docs/explanation/.

Safety And Change Management

  • Do not add new dependencies when the existing Spring Boot, JUnit 5, Mockito, and static asset stack is sufficient.
  • Do not introduce secrets, tokens, or environment-specific URLs into the repository.
  • Avoid network-dependent tests in CI-oriented code paths.
  • Preserve backward compatibility for public endpoints unless the task clearly requires a breaking change.

Good Defaults For Agents

  • Read the relevant controller, service, DTO, and existing tests before editing behavior.
  • After code changes, run the narrowest relevant test first, then the broader suite if the change crosses module boundaries.
  • Prefer updating existing docs and tests alongside code in the same task.
  • If a subdirectory develops specialized rules later, add a nested AGENTS.md close to that code instead of overloading this root file.