Repository navigation
docs enterprise conventions
This file defines how every document in docs/enterprise/ is written, identified and checked. It is the only place where identifier formats, templates and validation profiles are defined; other files reference it.
Nothing in docs/enterprise/ is runtime proof. A capability exists only when its task is done and its tests pass (AGENTS rule 12: "no target is runtime-complete without tests").
- Documents, code and commits are in English (AGENTS rule 14). User-facing product copy is specified in Brazilian Portuguese where the wording itself is a rule (badge text, status labels).
- Order of authority inside this plan: 16-decisions (decisions and conflicts) → 04-business-rules (shared rules) → module specifications in
modules/→ backlog tasks inbacklog/. A task never overrides a rule; a module never overrides a shared rule. - Existing repository rules (AGENTS, ADRs, product contracts) govern this plan. Accepted changes are recorded in 16-decisions and the corresponding ADR and contracts. Proposed changes are listed there as conflicts (
CX-nn).
New identifiers never reuse an existing namespace. Existing namespaces (checked on origin/dev at a97ba3b3) are: BR-001…BR-028 and UC-001…UC-015 (legacy Android); B-BR-<NS>-… and BUC-<NS>-… (backend and product contracts, about fifty <NS> codes including DRV, MAP, MEX, PAY, ESP, PR, ENT, ADM, STF, SYNC, NAV, CF); task namespaces P##-T##, PAY, ESP, DRV, FOR, FQ, OPT, MEX, EE, MAP, PRM, RST, CS, SEC; gates G##; ADR-001…023; D01…D18.
The request that originated this plan asked for rule identifiers shaped like BR-ORG-001. They are kept, and they differ from every existing rule by having no B- prefix and a three-digit number. Module codes that would read like an existing B-BR-<NS> code are avoided: offline sync is OFFL (not SYNC), routes and navigation are ROUTE (not NAV), internal administration is BACK (not ADM). The task prefix is EMP (Empresas), because ENT already names the granted-tier rules of ADR-023.
| Kind | Format | Example | Defined in |
|---|---|---|---|
| Request requirement | REQ-<section>.<n> |
REQ-05.3 |
17-traceability |
| Business rule | BR-<MODULE>-<nnn> |
BR-ORG-001 |
shared: 04-business-rules; module: modules/*.md §4 |
| Use case | UC-<MODULE>-<nn> |
UC-TRIP-03 |
modules/*.md §5 |
| Screen | SCR-<MODULE>-<nn> |
SCR-FUEL-02 |
modules/*.md §11 |
| Permission key | <module>.<resource>.<action> |
fleet.asset.assign |
07-permissions |
| Event | <module>.<entity>.<past-tense> |
trip.trip.completed |
modules/*.md §9 |
| Error code | UPPER_SNAKE |
MEMBERSHIP_ENDED |
09-architecture §6 |
| Indicator | IND-<nnn> |
IND-004 |
modules/intelligence |
| Finding type | FT-<nnn> |
FT-002 |
modules/intelligence |
| Microtask | EMP-<MODULE>-<nnn> |
EMP-ORG-003 |
backlog/ep*.md |
| Epic | EP<nn> |
EP06 |
backlog/INDEX |
| Phase | F0…F8 |
F3 |
14-roadmap |
| Milestone |
M0…M8, cut C1
|
C1 |
14-roadmap |
| Decision | EDR-<nnn> |
EDR-004 |
16-decisions |
| Conflict with an existing rule | CX-<nn> |
CX-01 |
16-decisions |
| Assumption | AS-<nn> |
AS-07 |
16-decisions |
| Open question | OQ-<nn> |
OQ-03 |
16-decisions |
| Validation scenario | VAL-<nn> |
VAL-05 |
15-validation |
| Journey | JRN-<nn> |
JRN-03 |
05-journeys |
| Legal validation point | LV-<nn> |
LV-05 |
11-privacy-security §10.4 |
Module codes used in rule, use-case, screen and task identifiers:
| Code | Scope | Specification |
|---|---|---|
TEN, SRC, TRUTH, MONEY, TIME, AUD, REV, AMD
|
Cross-cutting: tenancy, source separation, honest status wording, exact values, time, audit, review lifecycle, amendments | 04-business-rules |
PLAT, PRIV
|
Platform foundations, privacy and security | 09-architecture, 11-privacy-security |
ORG |
Organizations, legal entities, units, teams, cost centres | modules/organizations |
IDN |
Accounts, people, employees, memberships, credentials, devices | modules/identity |
AUTH |
Roles, scopes, permissions, active context | 07-permissions |
OFFL |
Offline operation queue and intake | 10-offline-sync |
FLEET, METER
|
Assets, assignments, meters | modules/fleet |
TRIP |
Missions, trips, logbook | modules/trips |
GPS, ROUTE
|
Tracking, live view, routes, navigation | modules/gps-navigation |
FUEL |
Fuelings and consumption | modules/fuelings |
DOC |
Receipts, fiscal documents, attachments | modules/documents |
EXP, APPR, BUDG, FIN
|
Expenses, approvals, budgets, payables | modules/expenses-finance |
MAINT, CHECK
|
Maintenance, checklists, incidents | modules/maintenance |
STOCK |
Internal fuel tanks | modules/fuel-stock |
KPI, FIND, RPT
|
Indicators, findings, reports and exports | modules/intelligence |
CLAIM |
Station claims and representation | modules/station-claims |
STN, AGREE
|
Station commerce, agreements, vouchers | modules/station-commerce |
SUBS, PUB
|
Subscriptions, entitlements, public products | modules/subscriptions |
DATA |
Abastevo Data | modules/data |
IMPORT, NOTIF, INTEG
|
Imports, notifications, integrations | modules/imports-notifications-integrations |
BACK |
Internal administration and support (back office) | modules/back-office |
GOV, REL
|
Decisions and discovery; release gates (tasks only) | backlog/ep00-governance, backlog/ep20-release |
Identifiers are stable. A retired identifier is marked RETIRED with its replacement and is never reused.
Every statement about the current repository carries one of these labels:
| Label | Meaning |
|---|---|
IMPLEMENTED |
Code and tests exist; the path is cited. |
PARTIAL |
Code exists, but a listed part is missing or not reachable in production. |
DOCUMENTED |
Described in an existing document only; no code. |
PROPOSED |
New in this plan. |
UNVERIFIED |
Could not be confirmed in this analysis; the limitation is stated. |
Paths to existing files are written as real repository paths. Paths that do not exist yet are always marked (proposed).
Every file in modules/ uses these twelve sections, in this order, with these headings. A section that does not apply states why in one line; it is never omitted.
- Purpose — problem solved, users, expected result.
- Scope — basic capabilities, later evolutions, out of scope.
- Entities and ownership — entities, relations, data owner, invariants.
-
Business rules —
BR-<MODULE>-nnn, one rule per line, each testable. -
Use cases —
UC-<MODULE>-nnwith preconditions, main flow, alternatives, result. - States and transitions — per state machine: actor, validation, effects, reversal.
- Roles and permissions — permission keys used, allowed roles, scopes.
- Offline, concurrency, idempotency and corrections.
- Events, notifications and integrations — produced, consumed.
- Data, formulas and examples — inputs, validations, formulas, outputs, worked numbers.
-
Screens —
SCR-<MODULE>-nnwith surface, objective, actor, data, actions, rules, permissions, accessibility, validations and the five states (loading, empty, error, unavailable, forbidden). - Acceptance, dependencies, risks, phase and microtasks.
Screen surfaces: APP (Android enterprise mode), PANEL (company panel in the business web), PORTAL (station portal in the business web), ADMIN (internal administration).
Shared screen states are defined once in 12-ux-app §3 and 13-ux-web §3; a screen lists only what differs from those defaults.
Each task in backlog/ep*.md uses this block. Field names are fixed so that the consistency check can parse them.
### Title
- **Meta:** module XXX · phase F0 · cut C1|- · priority P0|P1|P2|P3 · type T · size XS|S|M|L · state TODO
- **Objective:** what changes for a user or for the system, and which problem it removes.
- **Rules and use cases:** BR-…, UC-…
- **Depends on:** EMP-…, EMP-… (or `none`)
- **Read first:** the minimum documents and sections.
- **Scope:** in: … · out: …
- **Areas:** existing: real paths · new (proposed): paths
- **Steps:** 1) … 2) … 3) …
- **Deliverable:** the observable result.
- **Acceptance:** AC1 …; AC2 …; AC3 …
- **Negative cases:** authorization, isolation, concurrency and error cases that must be tested.
- **Validation:** profiles from §6 · migration: … · rollback: …
- **Risks and assumptions:** …
- **Done when:** the single condition that closes the task.Rules for tasks:
- One task produces one verifiable behaviour in one short working cycle of one agent. "Implement fleets" is an epic, not a task.
-
Depends onlists task identifiers only. The graph has no cycles; backlog/INDEX is generated from the task blocks and checked. - A dependency may sit in a later phase only when that dependency is tagged
cut C1(pulled forward for the first operational cut). -
Areasseparates existing paths from proposed ones. A proposed path follows the conventions in 09-architecture §2. - A field that does not apply says
n/a — <reason>. - Task types:
DECdecision,DISCdiscovery or spike,DOMpure domain,DBpersistence and transactions,APIuse case plus HTTP contract,APPAndroid,WEBbusiness web or internal admin,JOBbackground job,INTintegration or adapter,OPSoperations,TESTcross-cutting validation,RELrelease. - Sizes are relative and are hypotheses, not a calendar:
XSabout half a cycle,Sone cycle,Mtwo to three cycles,Lfour to six cycles. A cycle is one focused agent session ending in tested, reviewable work. A task that grows pastLis split with letter suffixes (EMP-TRIP-002a), keeping the original identifier as the parent. - Priorities:
P0required for cut C1;P1core of its phase;P2completes its phase;P3evolution with no committed phase exit. - States follow the repository vocabulary:
TODO,READY(dependencies done),IN_PROGRESS,LOCAL_DONE,INTEGRATED,BLOCKED(names the blocking decision).
A task names the profiles that apply to it. Every profile adds to the baseline in AGENTS rule 5: targeted meaningful tests, affected compilation, formatting and static checks, git diff --check, and a secret-surface review. Compile-only is never behaviour evidence. Commands are the evidence-backed ones in backend/README.md and TEST_STRATEGY; a profile does not invent command names.
| Profile | Proves | Minimum content |
|---|---|---|
V-DOC |
A decision or discovery task is complete | Decision record updated, links resolve, affected identifiers consistent, plan check passes (§7). |
V-DOM |
Pure rules | RED → GREEN → REFACTOR unit tests; Go domain packages stay standard-library only; Kotlin :domain tests. |
V-SQL |
Schema, queries, transactions | Integration tests against real PostGIS (-tags=integration), migration applied forward on a populated database, recovery note. |
V-ISO |
Tenant isolation | Two-organization fixture: every read, list, write, export, job and file access for organization A is attempted with organization B's identity and returns not-found or forbidden with no data in the error. |
V-AUTHZ |
Permissions | For each permission touched: allowed role and scope succeeds; wrong role, wrong scope, ended or suspended membership, suspended organization and missing entitlement are denied. |
V-IDEM |
Replay and concurrency | Same operation twice returns the first result; two different operations racing on one resource end in one consistent state; no lost update. |
V-MONEY |
Decimal behaviour | Golden vectors shared by Go and Kotlin (proposed contracts/testdata/enterprise/), including rounding boundaries. |
V-API |
Wire contract | OpenAPI updated, golden vectors validate against it, error envelope and codes match 09-architecture §6. |
V-SYNC |
Offline behaviour | Queue survives process death; duplicate, reordered and partial deliveries converge; nothing is dropped silently. |
V-APP |
Android behaviour | ViewModel and state tests, Compose state rendering for the five screen states, affected module compilation. Instrumented tests run on an emulator, never on the owner's device. |
V-WEB |
Web behaviour | Type check, component or state tests for the five screen states, keyboard and screen-reader checks for the changed screens. |
V-JOB |
Background work | Handler is safe to re-run; lease loss, retry and dead-letter paths tested; de-duplication key defined. |
V-PRIV |
Privacy | No personal data, location or document content in logs, events or public DTOs; retention behaviour tested with a controlled clock. |
V-PERF |
Capacity | Benchmark on a synthetic fixture with the measured numbers recorded; no claim without a measurement. |
V-E2E |
End-to-end | The named VAL-nn scenario in 15-validation passes. |
The plan is checked mechanically whenever it changes. The check verifies:
- every
EMP-identifier is defined exactly once, and every dependency exists; - the dependency graph has no cycle;
- every cut C1 task depends only on cut C1 tasks;
- no task depends on a later-phase task unless that task is cut C1;
- every
BR-,UC-andSCR-identifier referenced anywhere is defined exactly once; - every task references at least one rule or use case, or states why not;
- every
REQ-row in 17-traceability points to existing identifiers; - every relative link between plan documents resolves.
The check script and its last result are recorded in 15-validation §9. backlog/INDEX and the rule index at the end of 04-business-rules are generated by that script from the canonical sources and are never edited by hand.
- State behaviour before structure: a rule says what must be true, then a table or contract may show how.
- One fact has one home. Other documents link to it instead of restating it.
- Numbers that are product defaults are written as defaults with their configuration range; numbers that are hypotheses are labelled
(hypothesis). - Examples use synthetic data only. No real CNPJ, plate, person, document or location appears in this plan.
- "Verified", "validated" and "approved" are never used without saying what was checked, by whom and against which source.
- Home
- Roadmap
- docs-README
- docs-android-build
- docs-android-design-system
- docs-android-forum
- docs-android-games
- docs-android-map-engine
- docs-android-navigation
- docs-android-ocr-image
- docs-android-ocr-live-framing
- docs-android-premium-area
- docs-android-premium-integration
- docs-android-release
- docs-android-ui-containers
- docs-architecture-android-stack
- docs-architecture-android
- docs-architecture-backend
- docs-architecture-data-sources
- docs-architecture-overview
- docs-architecture-sources-ev-research
- docs-architecture-sources-national-limits
- docs-architecture-sources-national-stations
- docs-architecture-sources-register
- docs-assets-app-tutorial-CAPTURE_CONTRACT
- docs-assets-app-tutorial-FABLE_LANDING_POLISH_PROMPT
- docs-assets-app-tutorial-README
- docs-assets-attribution
- docs-assets-brand-README
- docs-assets-flags-ATTRIBUTION
- docs-assets-fuel-icons-README
- docs-assets-games-fuel-v1-README
- docs-assets-home-icons-README
- docs-assets-landing-fleet-android-20261012-BRIEF
- docs-assets-landing-hero-20261011-BRIEF
- docs-assets-landing-illustrated-20261012-BRIEF
- docs-assets-landing-illustrated-20261012-README
- docs-assets-landing-minimal-20261012-BRIEF
- docs-assets-landing-open-data-20261026-BRIEF
- docs-assets-landing-redesign-20261011-PREPARATION_EVIDENCE
- docs-assets-landing-redesign-20261011-README
- docs-assets-landing-redesign-20261011-REFERENCE_BRIEF
- docs-assets-landing-sync-20261012-BRIEF
- docs-assets-map-icons-README
- docs-backend-anp-ingestion
- docs-backend-api
- docs-backend-community-pricing
- docs-backend-data-model
- docs-backend-domain-model
- docs-backend-driver-private-data
- docs-backend-forum-architecture
- docs-backend-forum-bulletins
- docs-backend-forum-sources
- docs-backend-payments-provider-admission
- docs-backend-payments-provider-register
- docs-backend-photos-capture
- docs-backend-photos-subset-submission
- docs-backend-premium-api
- docs-backend-premium-cloud-protocol
- docs-backend-testing
- docs-backend-toolchain
- docs-brand-app-icons
- docs-brand-identity
- docs-decisions-001-kotlin-compose-stack
- docs-decisions-002-price-import-immutability
- docs-decisions-003-nominatim-reverse-geocode
- docs-decisions-005-modular-monolith-and-postgresql
- docs-decisions-006-official-catalog-and-exact-contracts
- docs-decisions-007-anonymous-proof-of-possession
- docs-decisions-008-privacy-and-retention
- docs-decisions-009-community-consensus-and-projections
- docs-decisions-010-private-object-evidence
- docs-decisions-012-licensing-and-hosted-business
- docs-decisions-015-kotlin-multiplatform-shared-domain
- docs-decisions-016-android-commercial-community-ios-deferred
- docs-decisions-017-station-profile-and-verified-representation
- docs-decisions-021-community-first-contribution
- docs-decisions-022-comaps-derived-native-map-engine
- docs-decisions-023-admin-suite-granted-tiers-contributors
- docs-decisions-025-private-abastevo-empresas-organization-boundary
- docs-decisions-026-multilingual-public-site
- docs-decisions-README
- docs-enterprise-README
- docs-enterprise-architecture
- docs-enterprise-backlog-INDEX
- docs-enterprise-backlog-ep00-governance
- docs-enterprise-backlog-ep01-platform
- docs-enterprise-backlog-ep02-organizations
- docs-enterprise-backlog-ep03-identity-access
- docs-enterprise-backlog-ep04-sync
- docs-enterprise-backlog-ep05-fleet-meters
- docs-enterprise-backlog-ep06-trips
- docs-enterprise-backlog-ep07-gps-navigation
- docs-enterprise-backlog-ep08-fuelings
- docs-enterprise-backlog-ep09-documents
- docs-enterprise-backlog-ep10-expenses-finance
- docs-enterprise-backlog-ep11-maintenance
- docs-enterprise-backlog-ep12-fuel-stock
- docs-enterprise-backlog-ep13-intelligence
- docs-enterprise-backlog-ep14-station-claims
- docs-enterprise-backlog-ep15-station-commerce
- docs-enterprise-backlog-ep16-subscriptions
- docs-enterprise-backlog-ep17-data
- docs-enterprise-backlog-ep18-imports-notifications-integrations
- docs-enterprise-backlog-ep19-back-office
- docs-enterprise-backlog-ep20-release
- docs-enterprise-business-rules
- docs-enterprise-contract
- docs-enterprise-conventions
- docs-enterprise-data-offering
- docs-enterprise-decisions
- docs-enterprise-domain-model
- docs-enterprise-glossary
- docs-enterprise-journeys
- docs-enterprise-modules-back-office
- docs-enterprise-modules-data
- docs-enterprise-modules-documents
- docs-enterprise-modules-expenses-finance
- docs-enterprise-modules-fleet
- docs-enterprise-modules-fuel-stock
- docs-enterprise-modules-fuelings
- docs-enterprise-modules-gps-navigation
- docs-enterprise-modules-identity
- docs-enterprise-modules-imports-notifications-integrations
- docs-enterprise-modules-intelligence
- docs-enterprise-modules-maintenance
- docs-enterprise-modules-organizations
- docs-enterprise-modules-station-claims
- docs-enterprise-modules-station-commerce
- docs-enterprise-modules-subscriptions
- docs-enterprise-modules-trips
- docs-enterprise-offline-sync
- docs-enterprise-permissions
- docs-enterprise-portal-routes
- docs-enterprise-privacy-security
- docs-enterprise-product-vision
- docs-enterprise-source-admission
- docs-enterprise-state-model
- docs-enterprise-testing
- docs-enterprise-ux-app
- docs-enterprise-ux-web
- docs-operations-README
- docs-operations-backup
- docs-operations-deploy-agent
- docs-operations-dou-editions
- docs-operations-edge-cache
- docs-operations-enterprise-activation
- docs-operations-map-static-overlay
- docs-operations-moderation-feedback
- docs-operations-moderation-profiles
- docs-operations-monitoring
- docs-operations-operator-access
- docs-operations-payments
- docs-operations-premium-billing
- docs-operations-recovery
- docs-operations-registry-daily-sync
- docs-operations-registry-runs
- docs-product-README
- docs-product-admin-tiers
- docs-product-community-community-first
- docs-product-community-experience
- docs-product-community-metrics
- docs-product-community-moderation
- docs-product-community-safety
- docs-product-community-terms-pt-br
- docs-product-driver-suite-README
- docs-product-driver-suite-android-state
- docs-product-driver-suite-cloud-sync
- docs-product-driver-suite-cost-profiles-and-maintenance
- docs-product-driver-suite-driver-model-and-earnings
- docs-product-driver-suite-foundation-decisions
- docs-product-driver-suite-gps-lifecycle
- docs-product-driver-suite-mobile-hub
- docs-product-driver-suite-odometer-review
- docs-product-driver-suite-outbox-wire
- docs-product-driver-suite-quick-refuel
- docs-product-driver-suite-reports
- docs-product-driver-suite-shifts-and-distance
- docs-product-driver-suite-signed-commands
- docs-product-ev-README
- docs-product-ev-charging-stop-planner
- docs-product-ev-energy-model
- docs-product-ev-financial-method
- docs-product-ev-journey-ui
- docs-product-ev-preparation
- docs-product-ev-typed-data
- docs-product-exploration
- docs-product-forum-contract
- docs-product-forum-policies
- docs-product-glossary
- docs-product-landing-content
- docs-product-landing-guides
- docs-product-landing-organic-growth-i18n-plan
- docs-product-licensing
- docs-product-map-discovery
- docs-product-map-favorites-and-trips
- docs-product-map-reports-routing-guidance
- docs-product-notification-content
- docs-product-official-prices
- docs-product-open-source-business
- docs-product-overview
- docs-product-payments-README
- docs-product-payments-offer-policy
- docs-product-premium-README
- docs-product-premium-financial-method
- docs-product-premium-source-policy
- docs-product-stations-catalog
- docs-product-stations-fuel-feedback
- docs-product-stations-fuel-quality
- docs-product-stations-identity-and-ev-catalog
- docs-product-stations-profile-contract
- docs-product-stations-profile-representation
- docs-product-stations-registry-sources
- docs-product-vehicle-registration
- docs-product-vehicles-and-occurrences
- docs-security-android-terms-acceptance
- docs-security-free-account-access
- docs-security-identity-profile
- docs-security-media-location-policy
- docs-security-privacy-notice
- docs-security-privacy-policy
- docs-security-retention
- docs-security-risks
- docs-security-security-privacy
- docs-store-README
- docs-store-play-readiness
- docs-store-play-store-listing
- docs-store-ugc-safety
Source: AlexandreZanata/Abastevo @ e4a67580fc368a59bc1c0f1e0466fc011313f330