Onboarding: BrasilAPI/BrasilAPI

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/BrasilAPI/BrasilAPI shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 3w ago
• 27+ active contributors
• Distributed ownership (top contributor 26% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live BrasilAPI/BrasilAPI repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BrasilAPI/BrasilAPI.

What it runs against: a local clone of BrasilAPI/BrasilAPI — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in BrasilAPI/BrasilAPI | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 52 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>BrasilAPI/BrasilAPI</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BrasilAPI/BrasilAPI. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BrasilAPI/BrasilAPI.git
#   cd BrasilAPI
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of BrasilAPI/BrasilAPI and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BrasilAPI/BrasilAPI(\\.git)?\\b" \\
  && ok "origin remote is BrasilAPI/BrasilAPI" \\
  || miss "origin remote is not BrasilAPI/BrasilAPI (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 52 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~22d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/BrasilAPI/BrasilAPI"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

BrasilAPI is a public REST API aggregating Brazilian data sources (CEP, banks, CNPJ, timezones, geographic coordinates, etc.) into unified endpoints. Built as a Next.js application with 255KB of JavaScript, it transforms fragmented Brazilian government and commercial data into standardized, free, and documented API responses. The project's mission is explicitly stated: 'transform Brazil into an API.' Next.js monolith with API routes under pages/api/ (e.g., pages/api/banks), shared middleware in middlewares/, utility libs in lib/, error hierarchy in errors/, and React components (Header) in components/. Uses SCSS modules for styling and integrates GitHub Copilot automation (.claude/hooks, .claude/settings.json) for PR review and development guidance.

Who it's for

Brazilian developers and applications needing reliable access to localized data (postal codes, financial institutions, geographic info) without implementing individual scrapers or integrations. Also serves as a reference implementation and contribution model for open-source Brazilian tech infrastructure.

Maturity & risk

Actively maintained and production-ready. The repo contains 255KB of JavaScript, comprehensive test coverage via Vitest, enforced CI/CD with GitHub Actions (e2e-tests.yml present), and established contribution workflows (CODE_REVIEW_GUIDELINES.md, copilot-instructions.md, pre-merge hooks). Node 20+ and npm 10+ are enforced, indicating modern standards.

Moderate risk: 50+ dependencies including external data sources (cep-promise, wikijs, selic) that may have availability issues; timezone lookup via tz-lookup and geocoding via external libraries create external dependency coupling. The firewall middleware (middlewares/firewall.js) and rate limiting (middlewares/cache.js) suggest operational maturity but also hint at past abuse/scaling issues. No major breaking changes visible but API surface is broad.

Active areas of work

Active development on endpoint documentation and contributor tooling. GitHub Actions workflows (e2e-tests.yml) run automatically. The .claude/ directory with pre-merge hooks and copilot instructions indicates recent investment in developer experience and automated code review. Husky pre-commit hooks (node >= 20, npm >= 10) suggest recent Node.js version bump and stricter dev environment standardization.

Get running

git clone https://github.com/BrasilAPI/BrasilAPI.git && cd BrasilAPI && npm install && npm run dev

Daily commands: npm run dev (starts Next.js dev server on port 3000 via next); npm run build && npm start for production; npm run test runs Vitest with hot-reload (concurrently runs next dev and vitest).

Map of the codebase

• pages/api: Contains all API endpoint implementations; this is the core business logic directory
• .github/copilot-instructions.md: Defines development patterns, endpoint creation workflow, and architectural principles enforced by GitHub Copilot automation
• .github/copilot-review-instructions.md: Specifies PR review criteria and automated validation rules that gate all contributions
• middlewares: Contains cross-cutting concerns: caching, error handling, firewall rules, and logging used by all API routes
• errors/BaseError.js: Root of custom error hierarchy used throughout API for consistent error responses
• docs/ENDPOINT_GUIDE.md: Reference documentation for creating new endpoints; onboarding guide for contributors
• package.json: Enforces Node 20+ and npm 10+; lists all external dependencies including data source integrations

How to make changes

To add a new endpoint: create file under pages/api/ (e.g., pages/api/newfeature.js) following patterns in docs/ENDPOINT_GUIDE.md; write tests in corresponding pages/api/tests/ directory; add validation using zod; leverage middleware stacks from middlewares/; add error handling via errors/ classes. To add utilities: place in lib/, use same error and logging patterns. To modify styles: edit components/**/*.module.scss.

Traps & gotchas

Node version must be >=20 <22 (enforced in engines field); npm >=10 required (not npm 8 or yarn). External API integrations (cep-promise, wikijs, selic, tz-lookup) may fail silently if their sources change; see lib/fetchGeocoordinateFromBrazilLocation.js and lib/fetchTimezoneNameFromBrazilLocation.js for fragility points. Husky pre-commit hooks will block commits if linting fails (enforced via .husky/pre-commit). SCSS setup via next.config.js; CSS modules required (not global CSS). GitHub Copilot automation reads .claude/hooks and .claude/settings.json; PRs without proper checklist completion (copilot-instructions.md) will be flagged automatically.

Concepts to learn

• API Gateway Pattern — BrasilAPI acts as an aggregation gateway, normalizing multiple heterogeneous Brazilian data sources (CEP, banks, CNPJ) into a single API surface; understanding this pattern is key to why each endpoint exists and how to add new ones
• Middleware Chain (Request/Response Pipeline) — The middlewares/ directory (cache, firewall, logger, errorHandler) implements a composable middleware stack that processes every request; understanding this is essential for debugging request flow and adding cross-cutting concerns
• Custom Error Hierarchy — BrasilAPI defines domain-specific errors (BadRequestError, NotFoundError, UnauthorizedError, UnprocessableEntityError) that map to HTTP status codes; this pattern ensures consistent error responses across all endpoints
• Schema Validation with Zod — The project uses zod for runtime schema validation (listed in dependencies), ensuring request/response types are enforced; critical for maintaining API contracts and preventing silent failures
• Cache-Aside (Lazy) Pattern — middlewares/cache.js implements caching strategy for expensive external lookups (geographic coordinates, timezone data); understanding TTL and cache invalidation is key to performance optimization
• Web Scraping & Data Integration — Libraries like wikijs, cep-promise, and selic are web scrapers/API integrators; BrasilAPI abstracts away their fragility and inconsistency, but contributors must understand how external data quality affects API reliability
• Automated Code Review (GitHub Copilot Orchestration) — The .claude/ directory and copilot-instructions.md files represent an advanced pattern where AI assists in code review; understanding how these instructions shape PR feedback helps contributors anticipate review requirements before submission

Related repos

• publicapis/public-apis — Comprehensive directory of free public APIs; BrasilAPI can be listed here and contributors can find inspiration from similar regional API projects
• awesome-selfhosted/awesome-selfhosted — BrasilAPI is a candidate for the 'APIs' section; useful for discovering self-hosted alternatives to commercial API services
• cep-promise/cep-promise — Direct dependency and companion project that BrasilAPI wraps; understanding its source and limitations is critical for CEP endpoint reliability
• vitest-dev/vitest — Testing framework used throughout BrasilAPI; developers need to understand Vitest config and patterns for writing tests
• vercel/next.js — Core framework; BrasilAPI is a reference implementation of Next.js API routes, middleware, and deployment patterns

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for CEP endpoints (v1 and v2)

The repo has two CEP endpoint versions (pages/api/cep/v1/[cep].js and pages/api/cep/v2/[cep].js) but the test structure is minimal. Given that CEP is a core Brazilian API feature and v2 likely has different behavior than v1, adding integration tests would catch regressions and document the differences between versions. This directly supports the e2e-tests.yml workflow already in place.

• [ ] Create pages/api/cep/v1/tests/[cep].test.js with valid/invalid CEP formats
• [ ] Create pages/api/cep/v2/tests/[cep].test.js comparing response differences from v1
• [ ] Test edge cases: malformed input, non-existent CEPs, boundary values
• [ ] Verify cep-promise dependency behavior is properly mocked/tested
• [ ] Run against existing vitest + @vitest/coverage-istanbul setup

Add unit tests for lib/parseRequest.js and middleware chain (cache, errorHandler, logger, firewall)

The lib and middlewares directories contain critical request handling logic but appear to have no dedicated test files. parseRequest.js handles request normalization, and the middleware stack (especially firewall.js with is-in-subnet) should be thoroughly tested. These are foundational to API reliability and security.

• [ ] Create lib/tests/parseRequest.test.js testing parameter extraction, validation, and edge cases
• [ ] Create middlewares/tests/cache.js testing cache hit/miss scenarios with different endpoints
• [ ] Create middlewares/tests/errorHandler.js testing error conversion (BadRequestError, NotFoundError, etc.)
• [ ] Create middlewares/tests/firewall.js testing IP subnet validation with is-in-subnet
• [ ] Create middlewares/tests/logger.js testing request/response logging format

Create E2E test workflow for CNPJ and CAMBIO endpoints with mocked external data sources

The repo has endpoints for CNPJ validation (pages/api/cnpj/v1/[cnpj].js) and currency exchange rates (pages/api/cambio/v1/) that likely depend on external APIs or data sources. Adding E2E tests with proper mocking would validate the entire request-response cycle, catch data format regressions, and document expected response schemas. This pairs with the existing e2e-tests.yml workflow.

• [ ] Create pages/api/cnpj/tests/cnpj-e2e.test.js testing valid/invalid CNPJ formats
• [ ] Create pages/api/cambio/tests/cambio-e2e.test.js testing currency quote endpoints and date ranges
• [ ] Mock external data sources (likely axios calls in the endpoint handlers)
• [ ] Use zod schemas from dependencies to validate response structures
• [ ] Add tests to verify error responses (BadRequestError, InternalError from errors/ directory)

Good first issues

• Add missing unit tests for middlewares/firewall.js and middlewares/cache.js (likely have minimal coverage); these gate all requests but have no visible tests directory
• Document the exact behavior of lib/fetchGeocoordinateFromBrazilLocation.js and lib/fetchTimezoneNameFromBrazilLocation.js in docs/ENDPOINT_GUIDE.md including failure modes and fallbacks (these are external integrations that deserve explicit docs)
• Add 2-3 new endpoint examples following docs/ENDPOINT_GUIDE.md pattern (e.g., a simple read-only endpoint for a public Brazilian dataset) with full test coverage, error handling, and SCSS component if UI needed; use as template for future contributors

Top contributors

• @lucianopf — 26 commits
• @LorhanSohaky — 21 commits
• @Copilot — 20 commits
• @bruno-arsi — 6 commits
• @RodriAndreotti — 2 commits

Recent commits

• 87af0ff — docs: adiciona verificação de duplicidade no processo de review (lucianopf)
• b2e819d — chore: remove GraphQL endpoint and related dependencies (#793) (LorhanSohaky)
• 6bb98d6 — refactor: Fase 1 — padronização de handlers, classes de erro e imports ESM (#794) (lucianopf)
• e22d750 — feat: b3 tickers (#680) (LorhanSohaky)
• bec2eae — feat: Investment Funds API (#528) (alanmareines)
• 64f5897 — feat: weather location cptec (#590) (enieber)
• d666ad4 — Corrige api de participantes do PIX com base no novo formato de csv do BCB (#751) (RodriAndreotti)
• 62b5487 — fix(cptec): add validation for integer days in swell predictions (#717) (gustavohenriquefs)
• 9ba39e3 — feat: add weekday field to holidays endpoint (#755) (BrzGab)
• 47888ef — fix: change no-else-return config in .eslintrc.js (#540) (jvolima)

Security observations

• High · Outdated Next.js Version — package.json - dependency: next@^12.3.4. The project uses Next.js 12.3.4, which is significantly outdated (released in 2022). This version contains known security vulnerabilities and lacks modern security features. Current stable versions are in the 14.x range. Fix: Upgrade to the latest stable Next.js version (14.x or higher). Review breaking changes and test thoroughly before deployment.
• High · Vulnerable Axios Version — package.json - dependency: axios@1.8.3. axios@1.8.3 may contain known security vulnerabilities. Consider auditing for potential prototype pollution or request handling issues. Fix: Update to the latest stable axios version (1.7.x or higher) and run 'npm audit' to identify specific CVEs.
• Medium · Outdated React Version — package.json - dependencies: react@^17.0.2, react-dom@^17.0.2. React 17.0.2 is outdated (released 2020). While not directly a security issue, it lacks security improvements and performance enhancements from React 18.x+. Fix: Upgrade to React 18.x or higher. This provides better concurrent rendering and security improvements.
• Medium · Potential XML External Entity (XXE) Vulnerability — package.json - dependency: fast-xml-parser@4.0.11, likely used in CPTEC endpoints. The project uses fast-xml-parser@4.0.11 for XML parsing. This version may be vulnerable to XXE attacks if not properly configured. Without seeing the implementation, the risk cannot be fully assessed. Fix: Ensure XXE prevention is enabled in fast-xml-parser configuration. Review all XML parsing implementations and disable external entity resolution and DTD processing.
• Medium · Outdated Core Dependencies — package.json - multiple dependencies. Several core dependencies are outdated: lodash@4.17.21, cors@2.8.5, and others. While lodash has known vulnerabilities in certain versions, and cors may lack recent security patches. Fix: Run 'npm audit' to identify specific vulnerabilities. Update all dependencies to their latest stable versions, especially security-critical ones like cors and lodash.
• Medium · Missing Security Headers Configuration — next.config.js, app.js. No evidence of security headers configuration (CSP, HSTS, X-Frame-Options, etc.) in visible files. Next.js 12 requires explicit configuration for security headers. Fix: Configure security headers in next.config.js using the 'headers' property. Implement CSP, HSTS, X-Content-Type-Options, X-Frame-Options, and X-XSS-Protection headers.
• Medium · Potential API Rate Limiting Bypass — middlewares/firewall.js. The 'firewall.js' middleware suggests rate limiting implementation, but without reviewing the actual code, the effectiveness cannot be verified. Insufficient rate limiting can lead to abuse. Fix: Review firewall.js implementation to ensure robust rate limiting. Consider using established libraries like express-rate-limit and implement per-IP/per-token rate limiting.
• Medium · Missing CORS Configuration Validation — middlewares/cache.js or app.js. The cors package is installed but configuration visibility is limited. Improper CORS setup can allow unauthorized cross-origin requests. Fix: Ensure CORS is configured with explicit origin whitelist (not '*'). Validate allowed methods and headers. Implement credential handling appropriately.
• Low · Unvetted Third-party Dependencies — package.json - dependencies: @djpfs/react-vlibras@2.0.2, wikijs@6.4.0. Several packages like '@djpfs/react-vlibras' and 'wikijs' appear to have limited maintenance or unclear security provenance. These increase supply chain risk. Fix: Audit third-party dependencies for maintenance status and security. Consider alternatives for unmaintained packages. Use npm audit and Snyk for continuous vulnerability scanning.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.