Repository navigation
Home
An open-source community for recent fuel prices at Brazilian stations. The commercial experience being planned helps people find a price, contribute a photo and keep station information current together. Community current-price projections lead the experience; ANP surveys are clearly dated reference data.
- Explore: simple city/fuel discovery, recent supported station prices, price conditions and directions. Browsing does not require an account or GPS.
- Contribute: capture a price photo, review suggested values and follow validation status. Private audit photos expire within 24 hours; a submission does not automatically become a trusted current price.
- Participate: free accounts, station/fuel ratings, 280-character comments/replies and validity votes. Price confidence, personal stars and community agreement are separate signals.
- Keep useful tools: offline reference, vehicles, calculations, ANP history and navigation remain available. Optional paid benefits never buy trust or restrict free social participation.
Backend/local infrastructure and P12–P17 functional modules are integrated; P18 local validation was merged in PR #67. Full functional device acceptance and real-production certification remain incomplete. The redesigned commercial experience below is PLANNED, not shipped. Current evidence separates implementation, integration and release readiness.
Android-first: P19 identity/navigation → P20 community discovery → P21 photo contribution → P22 social/moderation → P23 community operations → P24 Android commercial acceptance. Only afterward: separate P09/G09 real-production certification, bounded P10-T09 public pilot and optional P11 paid benefits. Complete commercial plan and experience specification.
iOS is archived and deferred until the maintainer explicitly requests resumption. Shared Kotlin ports, native source and prepared icon assets are preserved; no iOS build/device acceptance is claimed. Archived backlog, platform decision.
- Roadmap and bounded tasks, current progress and documentation index.
- Fast phase delivery, execution card and CI cadence: targeted TDD/risk checks per task, one phase branch/PR, protected quick verification at integration and wiki from the merged snapshot.
- Backend architecture, backend setup/tests, API contracts and infrastructure.
- Product contract, feedback rules, privacy/security and decisions.
- Approved brand, native app icons and agent entry point.
Based on brazil-fuel-prices-app, commit b8a52049e0294cd2d07612cedcc52b3017c5271e. Existing modules, com.anpfuel and MIT notices remain preserved. Production photos, credentials, contributor precise location and personal data do not belong in Git or public activity.
The following original README describes the upstream Android application and its release links. Its “no backend” description applies to that imported release; target platform plans are above. Known stale details (FTS version and UC index) are documented in the audit, not silently treated as implementation truth.
Open-source Android app to browse Brazilian ANP (National Petroleum Agency) weekly fuel price surveys — fully offline-capable, no backend required.
100% open source and free to use under the MIT License. The only requirement when reusing or redistributing this project is to reference the original source — see docs/license.md.
Install the signed release APK directly from GitHub — lightweight sideload, no Play Store required:
- Download v3.1.0 APK
- GitHub Releases — release notes and previous versions
See docs/releases/v3.1.0.md for the full v3.1.0 changelog.
- Vehicle profiles & tank fill cost — register up to 3 vehicles; Home shows estimated full-tank price (UC-010, UC-011)
- Optional device location — one-shot GPS + Nominatim reverse geocode after onboarding (UC-012)
- Station navigation — open Maps/Waze from station list (UC-013)
- Local price drop alerts — on-device notifications after weekly sync (UC-014)
- Survey week picker — choose latest or any historical ANP week (gov.br catalog parity)
- National city search — ~5 570 IBGE municipalities with FTS ranking and typo tolerance
- Automatic download of ANP price tables from gov.br/anp
- Browse average prices by fuel type, state, and city — vector icon per fuel
- Optional per-station detail (CNPJ, address, brand, price)
- Historical price trends (local storage)
- Edge-to-edge UI with system bar safe areas
- 100% on-device processing — no server
| Concern | Technology |
|---|---|
| Language | Kotlin 2.0+ |
| UI | Jetpack Compose + Material Design 3 |
| Architecture | Clean Architecture — :domain / :application / :data / :app
|
| Database | Room + SQLite + FTS5 |
| Background sync | WorkManager + OkHttp + Jsoup |
| XLSX parsing | Streaming XLSX parser (custom; Apache POI test-only) |
| DI | Hilt |
| i18n | Android string resources (en default, pt-BR) |
| Tests | JUnit 5 + MockK + Turbine |
Full specification: docs/tech-stack.md · ADR: docs/adr/001-kotlin-compose-stack.md
:app/ # Compose UI, ViewModels, theme, navigation
:application/ # Use cases (UC-001…UC-015)
:domain/ # Entities, Value Objects, rules, events, ports
:data/ # Room, OkHttp, parser, WorkManager, repositories
docs/ # Architecture, use cases, glossary
data/samples/ # Reference ANP spreadsheets for parser tests
.cursor/rules/ # Agent engineering contract
Package root: com.anpfuel
See docs/architecture.md for package layout, data flow, and database schema.
Reference files for week 2026-06-07 → 2026-06-13 are in data/samples/:
| File | Size | Rows | Purpose |
|---|---|---|---|
resumo_semanal_lpc_*.xlsx |
~287 KB | ~3.9K (municipalities) | Averages by region/state/city |
revendas_lpc_*.xlsx |
~1.8 MB | ~19.7K | Per-station prices |
See docs/data-sources.md for column schemas and download URL patterns.
| Document | Purpose |
|---|---|
| docs/user-business-logic.md | Product contract — user journeys, states, rules |
| docs/use-cases/ | Detailed use cases (UC-001 … UC-015) |
| docs/glossary.md | Domain language + business rules (BR-001 … BR-027) |
| docs/attribution.md | Third-party assets (fuel icons) |
| CHANGELOG.md | Release history |
| docs/architecture.md | Layers, packages, data flow, database |
| docs/tech-stack.md | Definitive stack — libraries and module deps |
| docs/adr/001-kotlin-compose-stack.md | Architecture decision record |
| docs/data-sources.md | ANP file formats and URL patterns |
| docs/commit-conventions.md | Git commit and PR standards |
| CONTRIBUTING.md | How to contribute — TDD, layers, i18n, PRs |
| docs/license.md | MIT license — free use, attribution required |
| docs/play-store-listing.md | Play Store listing draft (en + pt-BR) |
| docs/privacy-policy.md | Privacy policy — no personal data collected |
| docs/local-build.md | Local compile — debug APK, install, prerequisites |
| docs/release-build.md | Signed release APK/AAB build instructions |
| docs/releases/v3.1.0.md | GitHub Release v3.1.0 draft notes |
| docs/releases/v3.0.0.md | GitHub Release v3.0.0 draft notes |
| docs/releases/v2.0.0.md | GitHub Release v2.0.0 draft notes |
| docs/releases/v1.0.0.md | GitHub Release v1.0.0 draft notes |
| ROADMAP.md | Current phased execution plan; replaces the legacy git-ignored local plan |
Before implementing a feature:
- Read the use case in
docs/use-cases/(do not implement undocumented flows) - Check business rules in
docs/glossary.md - Verify stack and layer placement in
docs/architecture.md - Write domain tests first (TDD, GIVEN/WHEN/THEN)
- Add i18n keys for all user-visible strings
- Follow commit conventions (English, Conventional Commits)
See CONTRIBUTING.md for the full contributor guide.
./gradlew validateRepoBaseline # Gate 0.1 — repo + .cursor rules
./gradlew test # unit tests (same as CI)
./gradlew :app:assembleDebug # debug APK
./gradlew :app:installDebug # install on device/emulatorFull details: docs/local-build.md.
Latest: v3.1.0 — APK download · release notes. Previous: v3.0.0, v2.0.0, v1.0.0.
Validate a release locally:
./gradlew validateReleaseBuild # signed APK/AAB (v3.1.0)
./gradlew validateReleaseTag # version, license, disclaimers (Gate 15)
./gradlew validateGate15Release # tag, artifacts, release notes (Gate 15)
./gradlew publishGithubRelease # dry-run GitHub Release publish (R2.3)
./gradlew test # full unit test suite (all modules)See CHANGELOG.md for version history.
This project is released under the MIT License — free for any use (personal, commercial, modification, distribution). The only obligation is attribution: keep the copyright notice and reference the project origin.
Full details, examples, and FAQ: docs/license.md.
Fuel price data is published by ANP under open government data policies.