- Problem
- A live PEC read can hang or misbehave inside the process that owns the job queue and calculation.
- Decision
- Run live acquisition in an ephemeral Rust child process per job, with its own fault and resource boundary, while Java keeps the queue and calculation.
Observatório APS · local primary-care observatory
Esusdata
A local, read-only path from e-SUS PEC acquisition to verifiable extracts and versioned primary-care indicators, with publication controlled by evidence and methodology.
- Java 21
- Spring Boot
- Rust
- SQLite
- React
- PostgreSQL
- Problem
- A primary-care indicator needs reproducible source counts and a clear authorization boundary. A technically successful calculation cannot become an official result while its methodological interpretation remains unvalidated.
- Contribution
- Built a bounded Rust acquisition plane, a reproducible C1 calculation, and Java/SQLite coordination for authorization and staged publication.
- Key decision
- Keep the PEC immutable and stage technical results apart from publication, which needs both evidence and methodological approval.
- Repository
- Esusdata public repository ↗
01 / Context
Context & contribution
Problem
A primary-care indicator needs reproducible source counts and a clear authorization boundary. A technically successful calculation cannot become an official result while its methodological interpretation remains unvalidated.
Context
The public repository implements a local service with its own SQLite store, a Rust child process for bounded PEC reads and extract generation, and a Java indicator and result path. It describes tests against specific PEC versions; this page does not display municipal data or imply that the C1 methodology has been released.
Contribution
- Separated the PEC read-only source from the local service and kept acquisition inside an ephemeral Rust execution plane.
- Implemented bounded acquisition, extract validation, hashes, manifests, and reproducible calculation without reconnecting to the PEC.
- Built local Java/SQLite coordination for runs, authorization, result staging, evidence, and controlled publication.
- Encoded the C1 Mais Acesso rule while recording unresolved methodological gates rather than presenting it as an approved indicator.
- Developed an authorized web client for local results and scope-aware access.
02 / Technical choices
Engineering decisions
- Problem
- Recomputing or verifying a past result would otherwise require reconnecting to a PEC that may be unreachable or changed.
- Decision
- Treat a finalized extract and its checksummed manifest as a self-contained input, and reject anything with a missing or mismatched manifest.
- Problem
- Access can be revoked after the first authorization check of a job but before acquisition or publication runs.
- Decision
- Revalidate the grant of the requesting user before acquisition and again before publication, so a revoked account stops the next step without erasing history.
03 / Current state
Current state
Outcomes
- The public code connects source diagnosis, bounded acquisition, verifiable local extracts, indicator calculation, and scoped result access.
- The illustrative 3 scheduled and 2 walk-in encounters yield 60% / Ótimo only in a hypothetical target flow with all gates completed.
04 / Public record
Public evidence
Esusdata public repository
Pinned source for the Rust execution plane, Java/SQLite service, web client, tests, and current README.
Open public evidence ↗C1 methodology and implementation status
Documents the technical C1 proof and the methodological gates that still block release.
Open public evidence ↗PEC compatibility evidence
Version-specific acquisition and differential-check evidence; not a blanket compatibility claim.
Open public evidence ↗05 / Optional walkthrough
A paused, synthetic lifecycle of the system. Press Play or step through the chapters to explore states, failures and limits.
Systems Atlas / LifecycleSynthetic · hypothetical approved target
01 / 06
Authorize a scoped local run
A municipal grant authorizes a local run; the PEC stays outside the service.
Record
Authorize a scoped local run
Source captures
Read: 0 fictional encounters. Illustrative target C1 candidate: pending. Publication: not published. Consultation: municipal grant active. Dashboard: none.
Paused · operation 1 / 6
All counts are fictional: 3 scheduled, 2 walk-in, 1 unmapped excluded. 60% / Ótimo is a hypothetical target result only. No patients, clinical records, credentials or live PEC requests enter this page.
Read the complete lifecycle transcript
Calculated from the engine during the build. Available without JavaScript.
C1 · hypothetical approved target
Authorization
A municipal grant authorizes a local run; the PEC stays outside the service.
Read: 0 fictional encounters. Illustrative target C1 candidate: pending. Publication: not published. Consultation: municipal grant active. Dashboard: none.
Fictional encounter counts
Modality Count C1 treatment Synthetic six-row fixture · no patient or municipal records
Bounded read
The Rust child reads six fictional encounters under an explicit row budget.
Read: 6 fictional encounters. Illustrative target C1 candidate: pending. Publication: not published. Consultation: municipal grant active. Dashboard: none.
Fictional encounter counts
Modality Count C1 treatment Scheduled 3 Numerator Walk-in 2 Denominator only Unmapped 1 Excluded Synthetic six-row fixture · no patient or municipal records
Verifiable extract
A valid local extract and manifest retain provenance after source access closes.
Read: 6 fictional encounters. Illustrative target C1 candidate: pending. Publication: not published. Consultation: municipal grant active. Dashboard: none.
Fictional encounter counts
Modality Count C1 treatment Scheduled 3 Numerator Walk-in 2 Denominator only Unmapped 1 Excluded Synthetic six-row fixture · no patient or municipal records
C1 calculation
The pure rule counts three scheduled and two walk-in visits; one unmapped row is excluded.
Read: 6 fictional encounters. Illustrative target C1 candidate: 60% / Ótimo. Publication: not published. Consultation: municipal grant active. Dashboard: none.
Fictional encounter counts
Modality Count C1 treatment Scheduled 3 Numerator Walk-in 2 Denominator only Unmapped 1 Excluded Synthetic six-row fixture · no patient or municipal records
Conditional publication
Only a hypothetical target with all methodological gates completed can publish.
Read: 6 fictional encounters. Illustrative target C1 candidate: 60% / Ótimo. Publication: hypothetical target only. Consultation: municipal grant active. Dashboard: none.
Fictional encounter counts
Modality Count C1 treatment Scheduled 3 Numerator Walk-in 2 Denominator only Unmapped 1 Excluded Synthetic six-row fixture · no patient or municipal records
Authorized consultation
A live municipal grant exposes the hypothetical result and its evidence to the local dashboard.
Read: 6 fictional encounters. Illustrative target C1 candidate: 60% / Ótimo. Publication: hypothetical target only. Consultation: municipal grant active. Dashboard: 60% / Ótimo · hypothetical target.
Fictional encounter counts
Modality Count C1 treatment Scheduled 3 Numerator Walk-in 2 Denominator only Unmapped 1 Excluded Synthetic six-row fixture · no patient or municipal records
Read the three publication blockers
- A read budget below six rows stops acquisition.
- An invalid extract cannot reach calculation.
- A revoked municipal grant blocks publication and result reads.
Current state and operation
{
"type": "AUTHORIZE"
}06 / Limits & details
Limitations & details
Limitations
- Real C1 publication remains blocked while methodological source, interpretation, review, and approval gates are incomplete.
- The six-chapter tour uses fictional counts and a hypothetical approved target. It is not a patient record, production result, or claim of current C1 release.
- Public tests against documented PEC versions do not establish compatibility with every installation or a live deployment shown in this portfolio.
Reliability
- Source compatibility and read budgets fail closed before an unbounded or mismatched acquisition can become a result.
- Extract validation and checksums protect the calculation from partial or modified local files.
- Local tests and documented PEC-version checks exercise acquisition and recomputation; they do not substitute for methodological sign-off.
- Technical results are staged separately from publication, which requires both evidence and methodological approval.
System View
Architecture and component details
Conceptual local observatory. The PEC is a separate read-only source. C1 publication remains blocked by methodological gates in the current product.
Local observatory path
Follow a bounded source read into a verifiable extract, a gated result and an authorized view.
- Bounded source rows
- Verified extract
- Data file and manifest
- Versioned calculation
- Gated result
- Authorized evidence
Component details
The municipal PEC remains a separate PostgreSQL source, accessed with a read-only identity and no application writes.
Sends to
- Provides read-only source rows within a budget
An ephemeral child process probes source compatibility, enforces read budgets, streams rows, and creates the extract data file.
Receives from
- Provides read-only source rows within a budget
Sends to
- Writes and hashes a local extract
Local data files, record validation, byte limits, checksums, and manifests make calculation repeatable after the PEC connection closes.
Receives from
- Writes and hashes a local extract
Sends to
- Supplies a checked data file and manifest
One local service owns run state, locking, grants, manifest reconciliation, and atomic result publication in its own SQLite store.
Receives from
- Supplies a checked data file and manifest
Sends to
- Invokes the versioned indicator rule
The pure Java rule computes a versioned technical candidate. Methodological validation is still required before treating C1 as a released indicator.
Receives from
- Invokes the versioned indicator rule
Sends to
- Stages a result subject to methodological gates
Staging, evidence, history, and an atomic publication path exist; real C1 publication remains blocked by incomplete methodological gates.
Receives from
- Stages a result subject to methodological gates
Sends to
- Serves published evidence under a municipal grant
The local web client requests scoped results through the service; municipal grants constrain aggregate result access.
Receives from
- Serves published evidence under a municipal grant