ERP-RFC-001 — Licitação Vertical Engine

• Status: Draft
• Date: 2026-04-11
• Author: Koder Team
• Depends on: erp-RFC-000-architecture-overview.md, kompass-RFC-001-identity-and-org-unification.md
• Phase: 2 (Licitação engine extraction)
• Scope: new products/vertical/edictus/ module seeded from Crescer/c-corp/

Summary

Proposes a new vertical engine products/vertical/edictus that owns the full lifecycle of Brazilian public bidding (licitação pública): from PNCP edital ingestion through habilitação analysis, gono-go decision, proposta authoring, ICP-Brasil submission, contracting, execution, inspection, and payment tracking. The engine is seeded from the production-tested c-corp repository and depends on `servicesfoundationkompass for tenancy and servicesfoundation/id for identity per kompass-RFC-001`.

This RFC records the name decision (with Brand score analysis), the functional scope (what the engine does and does not do), the module layout (directory structure, subpackages), the dependency on other engines (BPM, form, sign, kompass, id, kdb, crm), the extraction plan from c-corp, and the Brazilian regulatory surface area.

Motivation

Why a dedicated engine

Public bidding is the revenue core for Crescer and Vivver. Losing a one-day window to respond to an edital means losing the contract. The current operation runs on:

• A Chrome extension bridging a Flutter web app to the PNCP portal, bypassing CORS
• A Node/Puppeteer proxy scraping the same portal from a server
• A Go/Rod headless-browser scraper doing the same job
• A Flutter screen (licitacoes_screen.dart, 1194 lines — the heaviest screen in the c-corp app) rendering results and driving action
• A Flutter app dedicated to PNCP search (apps/c_pncp) with regex filters, schedule automation, and export

The three scraping paths exist because PNCP actively resists scraping — rate limits, dynamic token requirements, browser fingerprinting, and random structural changes. The three paths are a failover network: when one path breaks, the other two keep working while the broken one is fixed. This defense-in-depth is battle-tested know-how that cost months to build and is irreplaceable by a "just scrape the API" design that assumes the API is cooperative.

All of this currently lives in Crescer/c-corp, a Flutter monorepo maintained outside the Koder Stack, with its own auth (Google OAuth + domain restriction), its own storage (PostgreSQL direct), its own IAM (modules/seguranca). It is functional but disconnected from every other module Koder ships.

A dedicated engine in the stack solves three things at once:

1. Reuse. Any future Koder product that touches Brazilian public procurement — a law firm tracking public-sector clients, a consultancy bidding for IT contracts, a construction company watching infra tenders — uses the same engine instead of rebuilding it.
2. Modernization. The engine refactors away the c-corp-specific debts (local auth, direct PG, own IAM) and adopts Koder ID + Kompass + KDB. The PNCP scraping logic is preserved exactly; the surrounding infrastructure is replaced.
3. Commercial byproduct. A FOSS Brazilian licitação engine running on top of Kompass, with ICP-Brasil signing, BPMN workflow, and a cross-platform flagship app, does not exist on the open-source market. TOTVS, Senior, and Sankhya charge enterprise prices; SEI is federal-only; SIAFI/COMPRASNET are government-owned. An engineering-led FOSS entrant with the right positioning has no real competitor.

Why not just add licitação as a Kompass submodule

Kompass is the universal tenant engine. Its promise is that the model is agnostic to tenant type — a church, a coworking space, a cooperative, a music label, and a Brazilian IT services firm should all look the same to Kompass. Adding "modalidade de licitação" enums, "CNPJ do órgão" foreign keys, "edital de pregão eletrônico" tables, and "análise de habilitação" workflows to Kompass core breaks that promise and pollutes every future non-BR non-bidding consumer.

The right pattern, already established by products/vertical/clinic (healthcare) and services/media (streaming), is a vertical engine that depends on Kompass for the substrate but owns its own domain model.

Name decision

Candidates and Brand scores

All scores computed per meta/docs/stack/specs/naming/brand-score.kmd, using the reference implementation in tools/namer/site/script.js.

Pick: edictus

Rationale. Edictus is the latin noun for "edict" — an authoritative public proclamation by a magistrate opening a legal procedure. In ancient Rome, the edictum praetorium was the pretor's formal pronouncement at the start of his term declaring which procedures he would recognize, which cases he would hear, and under what conditions. Every public procurement in Brazil today is likewise opened by a document called an edital, which is literally the Portuguese descendant of edictus ("edito" in pt, "edict" in en). The semantic chain edictus → edital → edital de licitação → the thing this engine parses is unbroken and historically rooted.

The Brand score is 78 (Great), above the 60+ threshold for engineplatform B2B modules per `specsnaming/brand-score.kmd. It is not the highest-scoring candidate — licitus scores 87 — but licitus has a fatal disqualifier: in English ears, it resonates with "illicit," which is the exact opposite of what a legal public bidding engine should project. edictus` has no such collision: "edict" in English is neutral-to-positive (official, authoritative, formal).

Alternative candidates seriously considered:

• licitare (Brand 84): The verb "to bid" in latin. Semantic fit is perfect, score is higher than edictus. Rejected because verb forms make awkward product names — compare "Licitare 2.0 has shipped" to "Edictus 2.0 has shipped." Also, "licitar" in pt is a transitive verb that reads clumsy as a noun.
• aedilis (Brand 79): Historically perfect — the aedile was the Roman official who supervised public works and managed tenders. Rejected because the concept is too obscure. A name only resonates if the audience can decode it without a history lesson.
• pregao (Brand 70): Maximum BR cultural fit. The pregão eletrônico is the most-used licitation modality under Lei 14.133/2021, and PNCP is built around it. Rejected because 70 is below the engine target (75 is the flagship target, 60 the engine minimum; 70 clears the bar but loses to edictus, and the descriptive character makes it collide if the engine ever wants to cover modalidades beyond pregão).

Module coordinates

Following the conventions in specs/landing-pages/products.kmd and docs/stack/engine-product-pattern.md:

Go module path:     flow.koder.dev/Koder/koder/products/vertical/edictus
Directory:          products/vertical/edictus/
Service id:         koder-edictus
Config file:        edictus.toml
Database namespace: koder_edictus
Domain (landing):   edictus.koder.dev
Landing page path:  products/vertical/edictus/site/index.html
Icon:               products/vertical/edictus/icon.svg

The engine is B2B-only at birth. It is a universal licitação engine, white-labelable for any tenant that needs public bidding capability. Flagship consumer product naming (if and when a dedicated app is built on top of it rather than absorbed into Mosaic or a new ERP flagship) is deferred to a follow-up RFC.

Scope

In scope

Core: PNCP ingestion

• Three-path scraping — preserved from c-corp as redundant paths:
  • Go + Rod headless browser (products/vertical/edictus/internal/scraper/rod/)
  • Node + Puppeteer proxy (products/vertical/edictus/tools/puppeteer-proxy/)
  • Chrome extension for authenticated local use (products/vertical/edictus/tools/chrome-extension/)
• Rate limiting and backoff tuned per the empirical behavior of the PNCP portal.
• Content hash deduplication — the same edital arrives through multiple paths and is normalized to a single record.
• Search parameters: modalidade, região, UF, município, CNPJ do órgão, período de publicação, regex sobre o objeto.
• Schedules — saved searches that run on cron and produce deltas (new editais, updated editais, closed editais) to subscribers.
• Export formats: Markdown, CSV, JSON, plain text. Preserved from c-pncp.

Edital parsing

• PDF extraction — editais are typically PDF attachments on PNCP. Parse text, tables, signatures, and embedded metadata (CNPJ, valor estimado, modalidade, prazos).
• Structured field extraction — object of bidding, minimum qualification, documentation requirements, jurisdictional rules (e.g. exclusive ME/EPP, cotas), session type (eletrônico, presencial), technical specifications.
• Annex handling — editais reference dozens of annexes (anexo I planilha, anexo II termo de referência, etc.). Each annex is ingested with its type classified.
• Amendment tracking — editais are updated mid-flight ("retificação"). Each amendment is captured as an event with a diff against the previous version.

Go/no-go decision

• Habilitação check — given the tenant's cadastral state (CNPJ, certidões, atestados, capital social), decide whether the tenant meets the edital's qualification requirements. Produces a report with greenyellowred per requirement.
• Opportunity scoring — heuristics for "is this edital worth responding to": geographic fit (does the tenant operate in the UF/município), technical fit (does the scope match known tenant capability), commercial fit (is the estimated value in the tenant's sweet spot), competitive fit (how many known competitors typically respond to similar editais in this órgão).
• Manual override — the go/no-go is advisory; a commercial analyst always makes the final call.

Proposta (proposal) authoring

• Template-based proposta generation — proposta templates are stored per tenant, parameterized by edital fields. products/vertical/edictus depends on products/horizontal/form for the form rendering when a proposta requires manual data entry.
• Price calculation — unit prices, BDI, impostos, composições. This is the most domain-specific area and deserves its own subpackage.
• Document assembly — PDF generation of the final proposta document with all required annexes.

ICP-Brasil signing and submission

• Digital signing — propostas must be signed with ICP-Brasil certificates. products/vertical/edictus depends on products/horizontal/sign for the signing primitives.
• Submission — PNCP does not offer a submission API for proposals. Submission happens through the portal UI, automated via the same scraping infrastructure that does ingestion. The three-path scraping doubles as a three-path submission network.
• Receipt capture — after submission, PNCP issues a protocolo with timestamp. The engine captures and stores it as the authoritative "we submitted by X timestamp" record.

Lifecycle after submission

• Sessão pública tracking — real-time capture of the session events: lances, desclassificações, recursos, ata.
• Ata de julgamento parsing — once the session closes, the ata is published on PNCP. The engine parses it and classifies the outcome (vencedor, 2º colocado, desclassificado, etc.).
• Contrato generation — if the tenant wins, a contrato is drawn up. StatusContrato from c-corp (rascunho → emAnalise → ativo → suspenso → encerrado → cancelado) is preserved as the contract lifecycle.
• Execution tracking — milestones, medições, relatórios de fiscalização.
• Payment tracking — NFS-e emission hooks into a future platform/fin-br for compliance. products/vertical/edictus owns the operational state; platform/fin-br (when it exists) owns the fiscal state.

Out of scope

• Non-Brazilian public procurement. Tender formats outside Brazil have different legal frameworks. A sibling engine — or an extension of products/vertical/edictus — can address them later. Not now.
• Private procurement / private RFPs. Private bidding is a different workflow (no legal framework, no PNCP, no ICP-Brasil). A horizontal procurement engine may appear later; it is not products/vertical/edictus.
• Tributação direta. NF-e, NFS-e, SPED, ICMS are owned by the future platform/fin-br engine. products/vertical/edictus holds the operational state and hands off to fin-br for fiscal emission.
• CRM functionality. Lead management, pipeline, opportunity CRUD are owned by services/foundation/crm (submodule of Kompass). products/vertical/edictus tracks editais and propostas; it does not reinvent CRM.
• Generic ticketing and helpdesk. Owned by platform/desk.
• BPMN modeling. products/vertical/edictus consumes the future BPM engine (erp-RFC-002) as a dependency. It does not build its own workflow runtime.
• Form design. products/vertical/edictus consumes products/horizontal/form for user input. It does not build a form designer.
• Signature primitives. Owned by products/horizontal/sign. Edictus calls sign for ICP-Brasil operations.

Architecture

Module layout

products/vertical/edictus/
├── README.md                        Module README (per specs/readmes/products.kmd)
├── CHANGELOG.md
├── icon.svg, icon-256.png, icon-512.png
├── edictus.toml                     Service config
├── go.mod
├── site/                            Landing page (per specs/landing-pages/products.kmd)
│   └── index.html
├── cmd/
│   ├── edictusd/                    Main daemon (HTTP API, scheduler, workers)
│   └── edictusctl/                  CLI for operators
├── docs/
│   ├── rfcs/                        Engine-internal RFCs
│   ├── domain/                      Domain glossary (edital, proposta, ata, etc.)
│   └── pncp/                        PNCP-specific operational notes
├── migrations/                      KDB migrations
├── internal/
│   ├── api/                         HTTP handlers, router
│   ├── config/                      Config loading
│   ├── scraper/
│   │   ├── rod/                     Go + Rod scraper path
│   │   ├── fetcher/                 Common HTTP/browser primitives
│   │   └── normalize/               Content dedup and normalization
│   ├── edital/                      Edital model and state machine
│   │   ├── parser/                  PDF + HTML parsing
│   │   └── amendments/              Retificação tracking
│   ├── habilitacao/                 Habilitação check engine
│   ├── gono/                        Go/no-go scoring heuristics
│   ├── proposta/
│   │   ├── authoring/               Proposta template engine
│   │   ├── pricing/                 Price/BDI/impostos calculation
│   │   └── assembly/                PDF assembly
│   ├── sessao/                      Session tracking
│   ├── ata/                         Ata parsing and outcome classification
│   ├── contrato/                    Contract lifecycle (extends c-corp StatusContrato)
│   ├── execucao/                    Execution tracking
│   └── integrations/
│       ├── kompass/                 Uses Kompass for tenancy/org
│       ├── id/                      Uses Koder ID for auth
│       ├── kdb/                     Persistence layer
│       ├── sign/                    Uses products/horizontal/sign for ICP-Brasil
│       ├── form/                    Uses products/horizontal/form for user input
│       └── bpm/                     Uses BPM engine for tramitação (when it exists)
├── tools/
│   ├── chrome-extension/            Chrome extension path (from c-corp/tools/pncp-extension)
│   └── puppeteer-proxy/             Puppeteer proxy path (from c-corp/tools/pncp-proxy)
├── backlog/
│   ├── pending/
│   ├── in-progress/
│   └── done/
└── br/                              Brazil-specific extension layer
    ├── cnpj/                        Receita Federal CNPJ lookup
    ├── ceis/                        CEIS/CNEP sanction list checks
    ├── certidoes/                   Certidão negativa verification
    ├── icpbrasil/                   ICP-Brasil cert validation
    └── pncp/                        PNCP portal specifics (structural changes, rate limits, tokens)

Component diagram

graph TB
  subgraph Edictus[products/vertical/edictus]
    Scraper[Scraper<br/>Rod/Puppeteer/Ext]
    Parser[Edital parser<br/>PDF + annex]
    GoNo[Go/no-go engine]
    Proposta[Proposta authoring]
    Sessao[Sessão tracking]
    Ata[Ata parser]
    Contrato[Contrato lifecycle]
    Execucao[Execução tracker]
    API[HTTP API]
  end

  PNCP[(PNCP portal<br/>external)]
  CNPJ[(Receita Federal<br/>CNPJ lookup)]
  CEIS[(CEIS/CNEP<br/>sanctions)]

  subgraph Depends[Koder Stack dependencies]
    Kompass[services/foundation/kompass]
    ID[services/foundation/id]
    KDB[infra/data/kdb]
    Sign[products/horizontal/sign]
    Form[products/horizontal/form]
    BPM[platform/BPM<br/>future]
    CRM[services/foundation/crm]
  end

  Scraper -->|scrapes| PNCP
  Scraper --> Parser
  Parser --> GoNo
  GoNo --> Proposta
  Proposta --> Sign
  Proposta --> Form
  Sessao -->|polls| PNCP
  Sessao --> Ata
  Ata --> Contrato
  Contrato --> Execucao

  API --> Kompass
  API --> ID
  API --> KDB

  GoNo --> CNPJ
  GoNo --> CEIS
  GoNo --> Kompass

  Contrato --> CRM
  Contrato -.->|future| BPM
  Sessao -.->|future| BPM

Data model highlights

Entities owned by products/vertical/edictus:

• Edital — one row per published edital, keyed by (orgao_cnpj, numero_edital, exercicio). Holds current state, last-seen-at, content hashes, amendment count, raw document references.
• EditalAmendment — append-only log of retificações.
• EditalAnnex — one row per attached annex, typed and classified.
• SavedSearch — a tenant's persisted PNCP search query with schedule.
• SearchRun — every execution of a saved search, with hit count, delta against previous run.
• GoNoGoAssessment — one row per (edital, tenant) pair; captures the automated scoring and the human decision.
• HabilitacaoCheck — line-item checklist of what the edital requires vs what the tenant has.
• Proposta — one row per (edital, tenant); lifecycle draft → signed → submitted → receipt-captured.
• PropostaItem — composição de preços line items.
• Submission — one row per submission attempt, with path (rodpuppeteerextension), protocol number from PNCP, timestamp.
• Sessao — one row per sessão pública observed, with event log.
• SessaoEvent — lance, desclassificação, recurso, fim-de-sessão events.
• Ata — one row per ata de julgamento, parsed.
• Contrato — inherited StatusContrato from c-corp plus edictus-specific metadata.
• ContratoMilestone, ContratoMedicao, ContratoPagamento — execution tracking.

Entities consumed from other engines:

• Tenant, Unit, Role, Membership from Kompass.
• Person, Credential, Email from Koder ID (indirectly; via membership).
• Cliente, Lead from CRM (services/foundation/crm sees the contratante órgão público as a special kind of Cliente).
• Signature, Certificate from products/horizontal/sign.
• FormDefinition, FormResponse from products/horizontal/form.

All tables partition by tenant_id (from the Kompass-owned Tenant). All rows carry created_at, updated_at, deleted_at per the stack-wide convention established in id-v2-RFC-002.

External APIs touched

• PNCP portal — https://pncp.gov.br. Non-cooperative surface; three scraping paths.
• Receita Federal CNPJ — https://www.receitaws.com.br or https://publica.cnpj.ws or direct SERPRO API if Crescer/Vivver has a contract.
• Portal da Transparência / CEIS / CNEP — sanction list lookups for habilitação.
• ICP-Brasil TSL — certificate validation; handled by products/horizontal/sign.
• Órgão-specific portals — many órgãos publish addenda outside PNCP. Out of initial scope; revisit after MVP.

Extraction plan from c-corp

Mapping

c-corp source                                            → products/vertical/edictus target
─────────────────────────────────────────────────────────────────────────────
middleware/internal/scraper/pncp.go                      → internal/scraper/rod/pncp.go
middleware/internal/api/handlers.go (PNCP endpoints)     → internal/api/pncp_handlers.go
middleware/internal/database/postgres.go                 → REMOVED; replaced by KDB via integrations/kdb
middleware/cmd/server/main.go                            → REWRITTEN as cmd/edictusd/main.go
tools/pncp-extension/                                    → tools/chrome-extension/
tools/pncp-proxy/                                        → tools/puppeteer-proxy/
apps/c_corp/lib/modules/comercial/screens/licitacoes_screen.dart   → apps/mosaic (or new ERP flagship) tab
apps/c_corp/lib/modules/comercial/models/contrato.dart   → internal/contrato/model.go (typed port)
apps/c_corp/lib/services/pncp_service.dart               → client-side port, read-only wrapper over the new API
apps/c_corp/lib/services/pncp_extension_service_*.dart   → preserved as-is in tools/chrome-extension bridge
apps/c_pncp/                                             → Decision deferred: keep as satellite app or absorb

Step order

1. Land kompass-RFC-001 — no edictus code merges until identity is unified.
2. Scaffold products/vertical/edictus/ with empty directories, README, icon, site placeholder, initial RFC copied from this document.
3. Port the Go scraper (middleware/internal/scraper/pncp.go) to products/vertical/edictus/internal/scraper/rod/. Keep the Rod-based logic verbatim; rewrite the storage interface to use infra/data/kdb instead of direct PostgreSQL.
4. Stand up edictusd with only the scraper and a minimal HTTP API. Deploy to s.k.lin. Point Crescer and Vivver's saved searches at it in parallel with c-corp (dual-write).
5. Port the Chrome extension and Puppeteer proxy to tools/chrome-extension/ and tools/puppeteer-proxy/. No behavioral changes.
6. Port the editalpropostacontrato data model into internal/edital/, internal/proposta/, internal/contrato/. This is the step that requires the most discipline: the c-corp Dart models must be translated into Go models that reference Kompass entities correctly, not c-corp's own IAM.
7. Port the Flutter screen licitacoes_screen.dart into apps/mosaic/lib/features/licitacao/. This screen is the UI entry point for the engine and the fastest way to validate that the API is usable.
8. Shadow period — for 60 days, c-corp and products/vertical/edictus run side by side. Crescer and Vivver use both. Daily diffs check that the two agree on the set of editais, their contents, and the state of any proposta/contrato.
9. Cutover — once the shadow period passes, c-corp's modules/comercial + middleware/internal/scraper + tools/pncp-* are deleted. Crescer and Vivver rely exclusively on products/vertical/edictus.
10. Expand scope beyond scraping — at this point the engine has parity with c-corp. The RFC-driven expansion (edital parser, habilitação check, go/no-go scoring, proposta assembly, ICP-Brasil signing, sessão tracking, ata parsing, contract execution) can begin phased feature by feature, each with its own engine-internal backlog ticket.

Constraint: preserve the three scraping paths

Every refactor along the way must preserve the three-path redundancy. A tempting optimization is "pick the best-performing path and drop the other two," but PNCP's resistance is adversarial and non-stationary — the path that works today is not necessarily the one that works next week. The three-path architecture is a load-bearing design constraint, not a transient implementation accident.

Brazilian regulatory surface area

Lei 14.133/2021 (Nova Lei de Licitações)

Supersedes Lei 8.666/93 as the governing statute for public procurement. Key concepts the engine must model:

• Modalidades: pregão, concorrência, concurso, leilão, diálogo competitivo
• Critérios de julgamento: menor preço, maior desconto, melhor técnica ou conteúdo artístico, técnica e preço, maior lance (leilão), maior retorno econômico
• Regimes de execução: tarefa, empreitada por preço global, empreitada por preço unitário, empreitada integral, contratação integrada, contratação semi-integrada
• Fases: preparatória, divulgação do edital, apresentação de propostas e lances, julgamento, habilitação, recursal, homologação
• Procedimentos auxiliares: credenciamento, pré-qualificação, sistema de registro de preços, cotação eletrônica
• PNCP obrigatoriedade: desde 2023, toda contratação regida pela nova lei deve ser publicada no PNCP

Decreto 10.024/2019 (Pregão Eletrônico)

Still in force for pregões eletrônicos, subordinated to Lei 14.133 since 2024. The engine handles both legal frameworks — older editais still appear regularly.

ICP-Brasil

Assinatura digital via ICP-Brasil (MP 2.200-22001) is mandatory for proposta submission in most modalidades. `productsverticaledictus delegates to productshorizontalsign for the cryptographic operations; productsverticaledictusbricpbrasil` handles the validation rules specific to procurement (which certificate types are accepted, which chains must be trusted, expiration handling).

LGPD

products/vertical/edictus processes CNPJs and limited personal data of responsible parties on the licitante side (proposta signatories, legal representatives). The engine is an LGPD "controlador" for tenant data and a "operador" for órgão-side data. Retention policies and right-to-be-forgotten flows inherit from the Kompass + Koder ID foundation.

CEIS / CNEP / CEPIM

Three public sanction lists that must be consulted during habilitação: companies barred from contracting with public administration. The br/ceis/ subpackage automates the checks against:

• CEIS: Cadastro Nacional de Empresas Inidôneas e Suspensas (Portal da Transparência)
• CNEP: Cadastro Nacional de Empresas Punidas (anticorrupção)
• CEPIM: Cadastro de Entidades Privadas sem Fins Lucrativos Impedidas

Checks are cached for 24 hours per CNPJ to respect rate limits on the source APIs.

e-CPF / e-CNPJ

Authentication to some órgão-level portals (SIASG, BEC-SP, e-Licitações, various state platforms) requires e-CPF or e-CNPJ smart cards. The engine does not handle smart-card authentication directly today; integration with hardware tokens is a br/ extension left for a future iteration.

Dependencies on other engines