ERPRFC001 — Licitação Vertical Engine

• *tatus:*Draft
• *ate:*20260411
• *uthor:*Koder Team
• *epends on:*erp-RFC-000-architecture-overview.md, kompass-RFC-001-identity-and-org-unification.md
• *hase:*2 (Licitação engine extraction)
• *cope:*new platform/edictus/ module seeded from Crescer/c-corp/

Summary

Proposes a new vertical engine platform/edictus that owns the full lifecycle of Brazilian public bidding (licitação pública): from PNCP edital ingestion through habilitação analysis, gonogo decision, proposta authoring, ICPBrasil submission, contracting, execution, inspection, and payment tracking. The engine is seeded from the productiontested ccorp repository and depends on `platformkompass for tenancy and platform/id for identity per kompassRFC001`.

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 *NCP 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 defenseindepth is battletested knowhow 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. *euse.*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. *odernization.*The engine refactors away the ccorpspecific 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. *ommercial byproduct.*A FOSS Brazilian licitação engine running on top of Kompass, with ICPBrasil signing, BPMN workflow, and a crossplatform flagship app, does not exist on the opensource market. TOTVS, Senior, and Sankhya charge enterprise prices; SEI is federalonly; SIAFI/COMPRASNET are governmentowned. An engineeringled 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 nonBR nonbidding consumer.

The right pattern, already established by platform/health (healthcare) and platform/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`*

*ationale.*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 *dital* 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/brandscore.kmd`. It is not the highestscoring 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 neutraltopositive (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/platform/edictus
Directory:          platform/edictus/
Service id:         koder-edictus
Config file:        edictus.toml
Database namespace: koder_edictus
Domain (landing):   edictus.koder.dev
Landing page path:  platform/edictus/site/index.html
Icon:               platform/edictus/icon.svg

The engine is B2Bonly at birth. It is a universal licitação engine, whitelabelable 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

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

Edital parsing

• *DF extraction*— editais are typically PDF attachments on PNCP. Parse text, tables, signatures, and embedded metadata (CNPJ, valor estimado, modalidade, prazos).
• *tructured field extraction*— object of bidding, minimum qualification, documentation requirements, jurisdictional rules (e.g. exclusive ME/EPP, cotas), session type (eletrônico, presencial), technical specifications.
• *nnex handling*— editais reference dozens of annexes (anexo I planilha, anexo II termo de referência, etc.). Each annex is ingested with its type classified.
• *mendment 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

• *abilitaçã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.
• *pportunity 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).
• *anual override*— the go/no-go is advisory; a commercial analyst always makes the final call.

Proposta (proposal) authoring

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

ICP-Brasil signing and submission

• *igital signing*— propostas must be signed with ICP-Brasil certificates. platform/edictus depends on platform/sign for the signing primitives.
• *ubmission*— 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 threepath scraping doubles as a threepath submission network.
• *eceipt 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

• *essão pública tracking*— real-time capture of the session events: lances, desclassificações, recursos, ata.
• *ta 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.).
• *ontrato 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.
• *xecution tracking*— milestones, medições, relatórios de fiscalização.
• *ayment tracking*— NFSe emission hooks into a future `platform/finbr for compliance. platformedictus owns the operational state; platformfin-br` (when it exists) owns the fiscal state.

Out of scope

• *on-Brazilian public procurement.*Tender formats outside Brazil have different legal frameworks. A sibling engine — or an extension of platform/edictus — can address them later. Not now.
• *rivate 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 platform/edictus.
• *ributação direta.*NFe, NFSe, SPED, ICMS are owned by the future platform/fin-br engine. platform/edictus holds the operational state and hands off to fin-br for fiscal emission.
• *RM functionality.*Lead management, pipeline, opportunity CRUD are owned by platform/crm (submodule of Kompass). platform/edictus tracks editais and propostas; it does not reinvent CRM.
• *eneric ticketing and helpdesk.*Owned by platform/desk.
• *PMN modeling.*platform/edictus consumes the future BPM engine (erp-RFC-002) as a dependency. It does not build its own workflow runtime.
• *orm design.*platform/edictus consumes platform/form for user input. It does not build a form designer.
• *ignature primitives.*Owned by platform/sign. Edictus calls sign for ICP-Brasil operations.

Architecture

Module layout

platform/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 platform/sign for ICP-Brasil
│       ├── form/                    Uses platform/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[platform/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[platform/kompass]
    ID[platform/id]
    KDB[platform/kdb]
    Sign[platform/sign]
    Form[platform/form]
    BPM[platform/BPM<br/>future]
    CRM[platform/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 platform/edictus:

• *dital*— one row per published edital, keyed by (orgao_cnpj, numero_edital, exercicio). Holds current state, lastseenat, content hashes, amendment count, raw document references.
• *ditalAmendment*— append-only log of retificações.
• *ditalAnnex*— one row per attached annex, typed and classified.
• *avedSearch*— a tenant's persisted PNCP search query with schedule.
• *earchRun*— every execution of a saved search, with hit count, delta against previous run.
• *oNoGoAssessment*— one row per (edital, tenant) pair; captures the automated scoring and the human decision.
• *abilitacaoCheck*— line-item checklist of what the edital requires vs what the tenant has.
• *roposta*— one row per (edital, tenant); lifecycle draft → signed → submitted → receipt-captured.
• *ropostaItem*— composição de preços line items.
• *ubmission*— one row per submission attempt, with path (rodpuppeteerextension), protocol number from PNCP, timestamp.
• *essao*— one row per sessão pública observed, with event log.
• *essaoEvent*— lance, desclassificação, recurso, fimdesessão events.
• *ta*— one row per ata de julgamento, parsed.
• *ontrato*— inherited StatusContrato from ccorp plus edictusspecific metadata.
• *ontratoMilestone* *ontratoMedicao* *ontratoPagamento*— execution tracking.

Entities consumed from other engines:

• *enant, Unit, Role, Membership*from Kompass.
• *erson, Credential, Email*from Koder ID (indirectly; via membership).
• *liente, Lead*from CRM (platform/crm sees the contratante órgão público as a special kind of Cliente).
• *ignature, Certificate*from platform/sign.
• *ormDefinition, FormResponse*from platform/form.

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

External APIs touched

• *NCP portal*— https://pncp.gov.br. Non-cooperative surface; three scraping paths.
• *eceita Federal CNPJ*— https://www.receitaws.com.br or https://publica.cnpj.ws or direct SERPRO API if Crescer/Vivver has a contract.
• *ortal da Transparência / CEIS / CNEP*— sanction list lookups for habilitação.
• *CP-Brasil TSL*— certificate validation; handled by platform/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                                            → platform/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. *and kompass-RFC-001*— no edictus code merges until identity is unified.
2. *caffold platform/edictus/*with empty directories, README, icon, site placeholder, initial RFC copied from this document.
3. *ort the Go scraper*(middleware/internal/scraper/pncp.go) to platform/edictus/internal/scraper/rod/. Keep the Rod-based logic verbatim; rewrite the storage interface to use platform/kdb instead of direct PostgreSQL.
4. *tand 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 ccorp (dualwrite).
5. *ort the Chrome extension and Puppeteer proxy*to tools/chrome-extension/ and tools/puppeteer-proxy/. No behavioral changes.
6. *ort the editalpropostacontrato data model*into internal/edital/, internal/proposta/, internal/contrato/. This is the step that requires the most discipline: the ccorp Dart models must be translated into Go models that reference Kompass entities correctly, not ccorp's own IAM.
7. *ort 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. *hadow period*— for 60 days, c-corp and platform/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. *utover*— once the shadow period passes, ccorp's modules/comercial + middleware/internal/scraper + `tools/pncp* are deleted. Crescer and Vivver rely exclusively on platform/edictus`.
10. *xpand scope beyond scraping*— at this point the engine has parity with ccorp. The RFCdriven expansion (edital parser, habilitação check, go/nogo scoring, proposta assembly, ICPBrasil 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 threepath redundancy. A tempting optimization is "pick the bestperforming path and drop the other two," but PNCP's resistance is adversarial and nonstationary — the path that works today is not necessarily the one that works next week. The threepath 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:

• *odalidades* pregão, concorrência, concurso, leilão, diálogo competitivo
• *rité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
• *egimes de execução* tarefa, empreitada por preço global, empreitada por preço unitário, empreitada integral, contratação integrada, contratação semi-integrada
• *ases* preparatória, divulgação do edital, apresentação de propostas e lances, julgamento, habilitação, recursal, homologação
• *rocedimentos auxiliares* credenciamento, pré-qualificação, sistema de registro de preços, cotação eletrônica
• *NCP 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 ICPBrasil (MP 2.20022001) is mandatory for proposta submission in most modalidades. `platformedictus delegates to platformsign for the cryptographic operations; platformedictusbricpbrasil/` handles the validation rules specific to procurement (which certificate types are accepted, which chains must be trusted, expiration handling).

LGPD

platform/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ãoside data. Retention policies and righttobeforgotten 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.

eCPF / eCNPJ

Authentication to some órgãolevel portals (SIASG, BECSP, eLicitações, various state platforms) requires eCPF or eCNPJ smart cards. The engine does not handle smartcard authentication directly today; integration with hardware tokens is a br/ extension left for a future iteration.

Dependencies on other engines