VINHO LAB COMP

Precision Enological Companion & Regulatory Benchtop Calculator

English (UK) · Português (Brasil) · Português (Portugal) · Español · 简体中文

Laboratory companion for enologists and wineries that cross-validates the same wine sample against two distinct regulatory frameworks — Brazil (MAPA, IN 14/2018) and Portugal / European Union (IVV; EU Reg. 1308/2013, 2019/934, and 2018/848 for organic wines) — and delivers an immediate, unambiguous exportability clearance verdict between them.

All processing executes 100% client-side in the browser: zero servers, zero analytics tracking, zero telemetry, and zero remote data transmission. Fully compliant with GDPR and air-gapped laboratory safety standards.

Warning

Decision-Support Instrument: This application is designed as a laboratory decision-support tool. It does not replace the official analysis bulletin issued by an accredited analytical laboratory. Regulatory limits and stoichiometric formulas stem verbatim from published legislation and official compendia, but official legal certification always remains the sole prerogative of an accredited testing institution.

---

01 / Navigation Index

• 02 / At a Glance
• 03 / Capabilities & Engineering
• 04 / Laboratory Modules & Showcase
• 05 / Control Surface & Bench Workflow
• 06 / Analytical Foundations & OIV Methods
• 07 / Installation & Development
• 08 / Pipeline Architecture & Codebase Layout
• 09 / Troubleshooting & Failure Modes
• 10 / Lineage & Provenance

---

02 / At a Glance

Vinho Lab Comp was created out of direct bench experience in wine analytical laboratories, where routine batches of chemical tests require swift unit conversions, stoichiometric calculations, and immediate regulatory cross-checking.

Key Architectural Strengths

Architectural Pillar	Technical Implementation	Practical Laboratory Guarantee
Dual Regulatory Matrix	Cross-validation engine matching MAPA (IN 14/2018) against IVV (Reg. 1308/2013)	Instant exportability clearance; automated conversion of meq/L ↔ g/L
OIV Bench Calculators	Raw bench readings ($V$, $N$, $m$, $V_{\text{am}}$) directly converted to final legal units	Zero approximated or invented formulas; strict stoichiometric molecular weights
100% Client-Side Privacy	Next.js 16 and React 19 running purely in browser memory	Zero remote data transfer; GDPR compliant; safe for proprietary winery blends
Sensory & Audit Trail	Official OIV 100-point tasting grid, defect taxonomy, and PDF/Markdown exports	Full calculation memory documenting exact bench titration readings
Density Table Rigour	Direct value entry preserved for TAV (% vol), dry extract, and Luff-Schoorl sugars	Refusal to invent polynomial fits over official non-linear OIV density tables

---

03 / Capabilities & Engineering

1. Regulatory Harmonisation (BR ↔ PT/EU)

Wineries seeking to export between South America and the European Union face differing regulatory benchmarks. Brazilian legislation (MAPA IN 14/2018) mandates total acidity expressed in milliequivalents per litre (meq/L), whereas Portugal and the EU (IVV / Regulation EU 1308/2013) express acidity in grams of tartaric acid per litre (g/L), and volatile acidity in grams of acetic acid per litre.

Vinho Lab Comp normalises and converts these parameters automatically using canonical stoichiometric factors ($75$ for tartaric acid, $60$ for acetic acid). It evaluates compliance simultaneously across diverse wine classes — including Still Wine (Vinho Tranquilo), Sparkling Wine (Espumante), Liqueur Wine (Licoroso), and Organic Wine (Vinho Biológico) — flagging exact borderline values.

2. Stoichiometric OIV Bench Calculators

Instead of requiring technicians to compute results on paper before entering them into validation sheets, the application accepts raw bench readings directly:

• Titration Formula: $\text{Result} = \frac{V \times N \times \text{Factor}}{V_{\text{sample}}}$
• Exact Molecular Coefficients:
  • Total Acidity: $75 = \frac{1}{2} M(\text{Tartaric Acid})$
  • Volatile Acidity: $60 = M(\text{Acetic Acid})$
  • Total & Free $\text{SO}_2$: $32 = \frac{1}{2} M(\text{SO}_2)$
  • Chlorides: $58.44 = M(\text{NaCl})$
  • Sulfates (Gravimetric): $0.7464 = \text{Barium Sulfate} \rightarrow \text{Potassium Sulfate}$
  • Ash: $(m \div V_{\text{sample}}) \times 1000$

Results computed in the calculator flow automatically into the Chemical Analysis module, adorned with an active green "Calculated" badge.

3. Sensory Assessment & Calculation Trail

• OIV 100-Point Evaluation Sheet: Standardised organoleptic scoring dividing sensory perception into Sight (limpidity, aspect), Smell (genuineness, positive intensity, quality), Taste (genuineness, body, persistence, quality), and General Harmony.
• Defect Taxonomy: Rapid flagging of common oenological flaws including Cork Taint (TCA), Oxidation, Volatile Acidity elevation, Reduction / $\text{H}_2\text{S}$, and Brettanomyces.
• Comprehensive Audit Trail: Exported PDF and Markdown reports feature an auditable "Calculation Memory" documenting the OIV method code, exact formula, reagent concentration, and titrant volume used for each parameter.

---

04 / Laboratory Modules & Showcase

Overview of Operational Modules

The application is structured into four cohesive bench modules accessible via top-level tabs:

Module	Core Functionality	Laboratory Scope
01 / Chemical Analysis	Physicochemical parameter validation against MAPA and IVV legal thresholds	Alcoholic strength (TAV % vol), Total Acidity, Volatile Acidity, Free & Total $\text{SO}_2$, Residual Sugars, Total Dry Extract, Sulfates, Chlorides, Total Ash, Heavy Metals ($\text{Cu}$, $\text{Pb}$, $\text{Fe}$, $\text{Cd}$, $\text{As}$), Ochratoxin A
02 / Results Calculator	Direct mathematical derivation from raw burette readings and analytical balances	Computes final legal concentrations using verbatim OIV-MA formulas; includes interactive "View OIV Method" drawer detailing reagents, apparatus, and procedure
03 / Sensory Analysis	Official international organoleptic evaluation	100-point OIV tasting scorecard with automatic classification (Excellent, Very Good, Good, Satisfactory) and fault checklist
04 / Results & Export	Exportability verdict, report compilation, and session portability	Cross-border compliance verdict, PDF generation via client-side pdfmake, Markdown download, and local .json session state backup/restore

---

05 / Control Surface & Bench Workflow

Typical Benchtop Workflow

1. Select Wine Category: Choose the sample's regulatory profile (e.g. Vinho Tinto de Mesa, Vinho Fino Branco, Espumante Natural, Vinho Biológico). Legal threshold limits adjust dynamically.
2. Perform Titrations / Gravimetry: Under the Calculadora de resultados tab, enter the volume of titrant consumed ($V$), reagent normality ($N$), and sample volume ($V_{\text{sample}}$).
3. Verify Compliance: Switch to Análise química to review the populated values. The interface displays green compliance checkmarks, amber measurement uncertainty alerts, or red non-compliance badges.
4. Conduct Sensory Tasting: Record organoleptic scores and identify any potential flaws in Análise sensorial.
5. Generate Audit Report: Under Resultados, inspect the cross-border exportability verdict and export the final document as a formal PDF bulletin or raw Markdown with full calculation memory.

---

06 / Analytical Foundations & OIV Methods

Verbatim OIV Method Registry

Parameter	Official OIV Code	Analytical Formula	Output Unit
Total Acidity	OIV-MA-AS313-01	$(V \times N \times 75) \div V_{\text{sample}}$	$\text{g/L (tartaric)}$
Volatile Acidity	OIV-MA-AS313-02	$(V \times N \times 60) \div V_{\text{sample}}$	$\text{g/L (acetic)}$
Total Sulfur Dioxide ($\text{SO}_2$)	OIV-MA-AS323-04B	$(V \times N \times 32 \times 1000) \div V_{\text{sample}}$	$\text{mg/L}$
Free Sulfur Dioxide ($\text{SO}_2$)	OIV-MA-AS323-04B	$(V \times N \times 32 \times 1000) \div V_{\text{sample}}$	$\text{mg/L}$
Chlorides	OIV-MA-AS321-02	$(V \times N \times 58.44) \div V_{\text{sample}}$	$\text{g/L (NaCl)}$
Total Ash	OIV-MA-AS2-04	$(m \div V_{\text{sample}}) \times 1000$	$\text{g/L}$
Sulfates	OIV-MA-AS321-05A	$(m_{\text{BaSO}4} \times 0.7464 \div V{\text{sample}}) \times 1000$	$\text{g/L } (\text{K}_2\text{SO}_4)$
Metals & Mycotoxins	Instrumental (AAS / HPLC)	$\text{Reading} \times \text{Dilution Factor}$	$\text{mg/L} \cdot \mu\text{g/kg}$

Note

Inviolable Principle — Zero Invented Values: All legal limits, analytical tolerances, and OIV procedures originate from immutable JSON definitions generated from legal reference databases (data/legal/*.json). Numerical constants represent strict stoichiometric realities ($75 = \frac{1}{2} M_{\text{tartaric}}$, $60 = M_{\text{acetic}}$, $32 = \frac{1}{2} M_{\text{SO}2}$, $58.44 = M{\text{NaCl}}$, $0.7464 = \text{BaSO}_4 \rightarrow \text{K}_2\text{SO}_4$).

---

07 / Installation & Development

System Requirements

• Runtime: Node.js 20+ or Bun 1.1+
• Package Manager: pnpm (recommended) or bun

Quick Start

# Clone the repository
git clone https://github.com/mastermaiolo/vinho-lab-comp.git
cd vinho-lab-comp

# Install dependencies
pnpm install

# Start local development server (Turbopack)
pnpm dev

The application will be available at http://localhost:3000.

Development & Quality Scripts

pnpm build    # Production build compilation
pnpm start    # Serve production build locally
pnpm lint     # Execute ESLint static analysis
pnpm test     # Run full unit test suite (bun test)
pnpm check    # Comprehensive validation: TypeScript types + lint + tests

---

08 / Pipeline Architecture & Codebase Layout

Repository Directory Tree

vinho-lab-comp/
├── app/                      # Next.js 16 App Router pages & UI components
│   ├── components/           # Modular bench components
│   │   ├── Field.tsx         # Analytical input with "Calculated" badge & method drawer
│   │   ├── CalculatorTab.tsx # OIV benchtop burette & gravimetric calculator tab
│   │   ├── SensoryTab.tsx    # OIV 100-point sensory grid & defect taxonomy
│   │   ├── ResultTab.tsx     # Cross-border exportability verdict & report triggers
│   │   ├── MethodPanel.tsx   # Expandable official OIV method documentation
│   │   └── DataToolbar.tsx   # Session JSON import/export persistent bar
│   ├── layout.tsx            # Root layout with Tailwind CSS v4 styling
│   └── page.tsx              # Reactive state orchestration & tab controller
├── assets/
│   └── readme/               # Modular SVG design system assets (hero, pipeline, etc.)
├── data/
│   └── legal/                # Single source of truth: immutable legal limits & OIV methods
├── lib/                      # Core mathematical & enological calculation engine
│   ├── calculators.ts        # OIV titration & gravimetric formulas (verbatim compute)
│   ├── canonical.ts          # Unit conversion algebra (meq/L ↔ g/L)
│   ├── validate.ts           # Dual-regime validation logic (MAPA & IVV)
│   ├── precision.ts          # OIV repeatability (r) & reproducibility (R) uncertainty
│   ├── plausibility.ts       # Physical sanity bounds checking for wine metrics
│   ├── markdown.ts           # Markdown report generator with calculation memory
│   ├── pdf.ts                # Client-side PDF generation via pdfmake
│   ├── session.ts            # Local session serialisation & schema validation
│   └── i18n/                 # Multilingual translation dictionaries (PT, EN, ES, ZH)
├── tests/                    # Bun unit test suite (46 automated regression tests)
├── docs/                     # Documentation graphics (banner.svg)
├── REGISTO-TRABALHO.md       # Portuguese engineering architectural log
└── DIARIO-CONSTRUCAO.md      # Laboratory development journal

---

09 / Troubleshooting & Failure Modes

Analytical Edge Cases & Mitigations

1. Unit Discrepancy (meq/L vs g/L)

Brazilian legislation expresses total acidity in meq/L, whereas European regulations mandate g/L tartaric acid. Comparing values across regimes without conversion produces severe compliance errors. Vinho Lab Comp routes all values through lib/canonical.ts, applying strict stoichiometric conversion factors ($0.075$ for tartaric, $0.060$ for acetic) before threshold checking.

2. Density Tables Without Closed Formulas

Parameters such as Alcoholic Strength by Volume (TAV % vol), Total Dry Extract, and Reducing Sugars determined via Luff-Schoorl titration rely on official empirical OIV density tables. Because no closed analytical polynomial represents these tables without interpolation error, Vinho Lab Comp deliberately avoids synthetic calculators for these metrics, requiring direct laboratory hydrometer/pycnometer entry to protect scientific integrity.

3. Export Clearance Rejection Between BR and EU

A wine may strictly comply with Brazilian standards while exceeding EU thresholds (e.g. total sulfur dioxide ceilings or volatile acidity limits in certain wine categories). When this occurs, the Results module isolates the non-compliant parameter in red, displays the exact delta, and cites the corresponding article of Regulation (EU) 2019/934 or MAPA IN 14/2018.

4. Measurement Uncertainty at Regulatory Boundaries

When an analytical result falls within the repeatability ($r$) or reproducibility ($R$) margin of a legal threshold, lib/precision.ts emits an amber boundary alert, advising the laboratory technician to perform a duplicate assay.

---

10 / Lineage & Provenance

Laboratory Genesis

"The idea for this project grew out of my own experience working in a wine-analysis laboratory, where I saw how a little practicality can make a real difference when running a battery of tests. By building this web app — with all data processing done directly on your own computer, with no values ever sent to a server — I hope to contribute to a smoother workflow in the lab and help produce results close to those of an official report, making it easier to gauge a wine's quality and legal compliance, and to see whether it meets Portuguese and Brazilian standards (including for export or import between the two countries).

This is a work in progress: for now, I recommend running the calculations separately and always double-checking the results.

I hope this project helps you — just as I hope it helps me."

— The Author

Standards & Regulatory References

• Federative Republic of Brazil: Ministério da Agricultura, Pecuária e Abastecimento (MAPA) — Instrução Normativa IN n.º 14, de 8 de fevereiro de 2018.
• Portuguese Republic & European Union: Instituto da Vinha e do Vinho (IVV) — Regulamento (UE) n.º 1308/2013, Regulamento Delegado (UE) 2019/934 e Regulamento (UE) 2018/848 (Vinhos Biológicos).
• International Standards: Organisation Internationale de la Vigne et du Vin (OIV) — Compendium of International Methods of Wine and Must Analysis.
• Author & Engineering: Master Maiolo · MAIOLO / SYSTEMS LAB.

Licence

Distributed under the MIT Licence. See the LICENSE file for complete terms.

---

_{MAIOLO / SYSTEMS LAB · VINHO LAB COMP · PRECISION ENOLOGICAL BENCH CALCULATOR}