DEV Community: Sandeep Chakravartty

A Skill Is More Than a Markdown File: Vetting scaffold-docs Against OWASP’s Agentic Skills Top 10

Sandeep Chakravartty — Tue, 27 Oct 2026 17:51:55 +0000

A documentation skill sounds like a low-risk addition to an AI agent. It reads code, proposes an outline, and helps write documentation.

But those activities cross security boundaries. The skill reads repository content that someone else may control, carries context between sessions, and asks an agent to write files. Its safety depends on both its instructions and the permissions available to the agent.

We evaluated scaffold-docs, an existing documentation-writing skill, against the OWASP Agentic Skills Top 10. We then implemented a limited set of improvements and checked whether its original workflow still worked.

The most useful finding was not a hidden malicious command. It was how easily ordinary workflow instructions can leave trust, permissions, and completion state underspecified.

What we reviewed

The skill organizes documentation into three sections:

Getting Started: a representative tutorial.
Diving Deeper: explanations of concepts and design decisions.
Reference: API documentation.

Its workflow is deliberately iterative. The user selects an audience, reviews the structure, and approves successive drafting passes. An update mode uses stored metadata to reconcile documentation after code changes.

We pinned the review to commit e234e13eb1ab9561a1da9a5a150c3deee3c515b8. That matters: a security assessment applies to the content reviewed, not automatically to whatever appears on the default branch tomorrow.

We also pinned the OWASP reference material and used its AST01–AST10 categories. This is the Agentic Skills Top 10, distinct from OWASP’s Agentic Applications taxonomy.

Start by treating the skill as evidence

We cloned the repositories into an isolated cloud workspace and inspected the target without installing it as an active skill.

That distinction was essential. A file under review may contain instructions addressed to an agent. Those instructions are evidence to analyze, not authorization to follow.

The review covered all 15 tracked files, including hidden metadata, phase instructions, bundled references, and historical implementation plans. We recorded file hashes and inspected file types and instruction content.

No intentionally malicious payload was identified in that snapshot. There were no bundled executable scripts or required remote instruction fetches.

That was a useful observation, but it was not a safety verdict. Natural-language instructions can still influence an agent’s actions without shipping executable code.

Use OWASP as a set of questions

We mapped the skill against all ten categories:

OWASP category	Main question
AST01 — Malicious Skills	Does the package contain deceptive or harmful instructions?
AST02 — Supply Chain Compromise	Can users identify and verify the content they install?
AST03 — Over-Privileged Skills	What access does the workflow need, and what access could it inherit?
AST04 — Insecure Metadata	Are persisted values validated before influencing behavior?
AST05 — Untrusted External Instructions	Can source material become agent authority?
AST06 — Weak Isolation	Which boundaries does the host actually enforce?
AST07 — Update Drift	Can reviewed content change without another review?
AST08 — Poor Scanning	Does validation examine prose and behavior as well as code?
AST09 — No Governance	Are installation, ownership, approval, and revocation accounted for?
AST10 — Cross-Platform Reuse	Would another host preserve the same security properties?

The framework helped organize the investigation. It did not turn every missing feature into a confirmed vulnerability.

For example, the absence of a permission manifest does not prove that a particular host grants excessive access. It means the deployment needs closer examination.

Separate observations from exploit claims

We combined manual instruction review with small, disposable fixtures.

One fixture tested the update workflow’s documented comparison:

git diff <baseline>..HEAD --stat

After modifying a tracked source file and adding an untracked API file, that comparison remained empty because neither change had been committed.

The command behaved correctly. The workflow’s scope was the problem: it did not clearly state whether it documented committed source or the current working tree.

Another fixture showed that a documentation filename could resolve through a symlink outside the intended directory. We did not write through that link.

These findings support different conclusions:

The Git comparison demonstrably omits working-tree changes.
The symlink fixture demonstrates a containment precondition.
Neither test proves that an agent would perform an unauthorized write or escape its host sandbox.

That distinction keeps a security report actionable without overstating its evidence.

Be precise about isolation

The assessment ran in an isolated cloud task, but network access remained enabled for retrieving source material.

We also attempted a stronger nested Bubblewrap sandbox with network isolation. It failed during UID-map setup, before the child command ran.

We continued with static review and harmless local fixtures. We did not describe the assessment as air-gapped or claim that the additional sandbox boundary worked.

A useful rule emerged: report the boundary you verified, not the boundary you intended to create.

The biggest gaps were in trust and state

The review identified several improvement areas.

First, the skill asked the agent to read comments, examples, existing documentation, and audience metadata without explicitly separating those inputs from instructions that could authorize actions.

A stored audience description should influence tone and depth. It should not be able to grant tool permissions or skip a checkpoint.

Second, file-access scope was undefined. Relative output names did not establish where writes were permitted, and editorial checkpoints did not enforce filesystem containment.

Third, installation guidance allowed copying or symlinking the skill directory without a package-wide integrity procedure. A reviewed skill can drift if its installed resources change.

Finally, synchronization metadata needed a clearer lifecycle. Further evaluation found that the creation workflow recorded a “last synced” commit during planning—before the documentation was complete.

An interrupted session could therefore leave behind a convincing-looking sync marker for unfinished work.

Implement a focused set of changes

We limited implementation to four recommendation groups:

R1: explicit instruction/data boundaries and trusted approval recovery.
R3: separate in-progress work from completed synchronization.
R4: validate metadata and use a stable, explicit source revision.
R7: resolve audience precedence and non-Git behavior.

The modified workflow now keeps documentation in progress until the selected buckets are complete or explicitly excluded. Updates retain the previous completed baseline while new work is pending.

Git mode documents a captured committed snapshot. Dirty and untracked source is disclosed as excluded, and source reads use the captured commit consistently.

Audience handling also became deterministic: an existing audience remains active even when the user has disabled further audience prompts.

We explicitly left R2, R5, R6, and R8 unimplemented. Those cover broader filesystem enforcement, installation integrity, adversarial regression infrastructure, and runtime support or governance. Adding instructions does not complete those controls.

Functional validation caught a regression

Security improvements can break normal workflows.

During validation, we found that phase-entry checks rejected a completed record whenever HEAD had advanced. But a new commit is exactly what normally triggers a documentation update.

We corrected the distinction:

State validation permits a completed record to reference the previous target.
Starting an update captures the new target.
Active source reads and completion still reject an unexpected HEAD change during the session.

After that correction, 30 checks passed. They covered state transitions, committed-source reads, interrupted work, updates, non-Git completion, and preservation of the original editorial instructions.

The original prose, headline, audience, and topic-selection references remained unchanged. The drafting passes and review checkpoints were preserved.

These were deterministic checks with simulated documents and approval outcomes. They did not establish end-to-end writing quality, real human-review behavior, or universal resistance to prompt injection.

Lessons for skill authors and reviewers

Review prose as part of the attack surface.

A Markdown-only package can still direct consequential tool use.

Keep editorial preferences separate from authority.

Audience descriptions, comments, and prior documents should guide content—not permissions.

Model completion honestly.

“Planning started,” “draft approved,” and “documentation synchronized” are different states.

Choose a source boundary and use it consistently.

Comparing committed changes while reading uncommitted files produces an ambiguous result.

Distinguish skill guidance from host enforcement.

A rule against writing outside a directory is useful. A host that denies the write provides a stronger boundary.

Test the ordinary path after hardening.

The update-entry regression was found through functional validation, not through searching for malicious payloads.

The resulting vetting repository contains the original assessment, recommendations, scoped implementation, and validation evidence. Its findings describe what was observed, what was changed, and what still needs testing—the distinctions a useful skill-security review should preserve.

SlothMode: A Quest Generator That Gives You Permission to Do Less

Sandeep Chakravartty — Mon, 26 Oct 2026 00:15:08 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady
What I Built
SlothMode turns a few choices—your energy, mood, available time, location, and constraints—into a tiny, playful quest. You can accept it, reroll it, mark it “Done-ish,” or choose to do nothing. There are no streaks or deadlines. Even intentional rest earns fictional points.

The app saves your preferences and adventures in your browser. You can export your history as JSON or download a personalized PNG certificate. No account is needed.
Demo
There isn’t a deployed demo or video yet. You can run the handcrafted demo locally without installing a model:
git clone https://github.com/scha54/SlothMode.git
cd SlothMode
npm ci
npm run dev
Open http://localhost:3000, select Demo · handcrafted quests, and click Find My Perfect Nothing. These quests are clearly labeled as handcrafted; they are not AI-generated.

Desktop screenshot · Mobile screenshot · Example certificate
Code
The source, setup instructions, tests, and architecture notes are in the SlothMode GitHub repository.

The central AI boundary is deliberately small. The model selects values for a versioned activity plan:
const activityPlanSchema = z.object({
version: z.literal(1),
activity: z.enum(["imagine", "remember", "observe", "rest"]),
subject: z.enum([/* 16 reviewed subjects /]),
setting: z.enum([/ 12 reviewed settings /]),
twist: z.enum([/ 12 reviewed twists */]),
}).strict();
Application code turns that plan into the words the user sees. The model cannot supply unrestricted instructions. If its response fails validation, SlothMode reports an error instead of quietly passing off a handcrafted quest as AI output.
How I Built It
SlothMode uses Next.js, React, TypeScript, Zod, and Dexie. IndexedDB stores preferences, quest history, rewards, and certificate details locally in the browser. The interface includes keyboard controls, reduced-motion support, and an original animated SVG sloth.

For local AI, the server adapter targets Gemma 3 4B through Ollama. It sends the user’s preferences and recent quest titles to Ollama’s structured JSON chat endpoint. The response must match the activity-plan schema before the app compiles it into a quest. The separate handcrafted catalog keeps the demo usable when Ollama is unavailable.

The default model’s manifest digest is pinned, but a full model download and live Gemma inference have not yet been validated. The completed checks cover the app and handcrafted demo: 33 unit tests, nine production browser tests, a production build, and a demo API smoke test. They establish that the demo workflow works; they do not establish live AI output quality or latency.
Why Does Open Innovation Matter?
A local, open-weight model lets this project explore playful generation without requiring users to create an API account or send their preferences to a hosted model provider. The model, prompt, output schema, and validation code are inspectable and changeable. Someone can run the app locally, swap in a compatible model, or improve the activity vocabulary.

That openness also makes the limits visible. The current AI design is intended for local use; it should not be presented as a working Vercel AI deployment. For now, the reliable public-facing path is the clearly labeled handcrafted demo, while the open-source code provides a foundation for testing and improving local inference.

Building Climate Court: Evidence-First Climate Investigations with Next.js, Optional AI, and Verifiable Reports

Sandeep Chakravartty — Sat, 24 Oct 2026 09:46:57 +0000

How we built a local-first investigation platform—and why the most valuable improvements came from testing what happens when things go wrong.

Corporate sustainability claims often sound precise:

“We reduced our carbon emissions by 40%.”

But precision in wording does not necessarily mean precision in evidence.

Reduced compared with which year? Does the figure describe absolute emissions or emissions intensity? Which operations are included? What happened to supply-chain emissions?

Climate Court was built to make those questions visible.

The application helps users organize a climate claim into assertions, inspect supporting material, identify evidence gaps, and produce a transparent report. A finalized report can then be fingerprinted and registered on a local blockchain for independent integrity verification.

The central design principle is simple:

Every finding should point to evidence—or explain what evidence is missing.

What Climate Court Actually Does

The core workflow is:

Submit a climate-related claim.
Add pasted source material or a text-based PDF.
Extract atomic assertions and identify ambiguities.
Inspect evidence classifications, passages, and provenance.
Generate and finalize a versioned report.
Register its snapshot hash on a local EVM.
Recompute the hash and compare it with the registered record.

The application includes a dashboard, investigation workspace, printable reports, JSON exports, version history, audit explorer, and demo controls.

It runs locally without paid API keys or cloud accounts.

That independence matters. An investigation should remain usable when an optional model is unavailable, a quota is exhausted, or the local blockchain is offline.

There is also an important boundary: user-provided documents are not automatically authenticated. They remain inconclusive pending independent review. Clearly labeled synthetic fixtures demonstrate supporting and contradictory classifications without implying that the platform has independently verified real companies.

The Technology Stack

Layer	Tools
Interface	Next.js App Router, React, TypeScript, Tailwind CSS, Lucide
HTTP backend	Next.js server-side route handlers
Runtime validation	Zod
Local persistence	Schema-validated JSON with atomic replacement and backups
Optional cloud persistence	Supabase PostgreSQL
Optional AI	Official Gemini SDK
Report integrity	Canonical serialization and SHA-256
Blockchain	Solidity, Hardhat, Ethers.js
Automated testing	Node’s test runner, tsx, Playwright, Chromium
Release checks	GitHub Actions, secret scanning, dependency auditing

We kept the application as a monolith. The challenge did not require independently deployed services; it required clear boundaries and predictable failure behavior.

Architecture: A Small Monolith with Explicit Responsibilities

The architecture separates presentation, orchestration, business rules, persistence, and external adapters.

flowchart TD
    User[Presenter or authenticated operator]
    Gateway[Access boundary]
    UI[React workspace]
    API[Validated API routes]
    Cases[Case services]
    Engine[Deterministic assessment engine]
    Store[Repository adapter]
    Audit[Audit service and reconciliation]
    PDF[Bounded PDF child process]
    AI[Optional Gemini adapter]

    User --> Gateway --> UI --> API
    API --> Cases
    Cases --> Engine
    Cases --> Store
    Cases -.-> AI
    API --> PDF
    API --> Audit
    Audit --> Store
    Audit --> EVM[Local Solidity registry]
    Store --> Local[(Local JSON)]
    Store -.-> Cloud[(Optional Supabase)]

The main modules reflect those responsibilities:

lib/engine.ts handles extraction, assessment, deduplication, and snapshots.
lib/services.ts orchestrates case operations and audit state transitions.
lib/store.ts handles persistence.
lib/chain.ts communicates with the registry.
lib/ai.ts provides optional interpretation.
lib/readiness.ts checks required dependencies.
Dedicated report, presentation, and API-client modules support the interface.

This structure made it possible to improve reliability without replacing the framework or introducing a message broker.

Deterministic Assessment Before AI Interpretation

Climate Court’s core assessment does not depend on an LLM.

Deterministic extraction identifies explicit quantities, units, reporting years, and qualifiers. It preserves unresolved questions rather than supplying missing context.

For example:

“Our emissions fell 40% last year.”

The platform can extract the percentage while leaving the reporting period unresolved. It should not silently decide which year “last year” refers to.

The assessment uses these verdict labels:

SUPPORTED
PARTIALLY_SUPPORTED
CONTRADICTED
INSUFFICIENT_EVIDENCE
UNRESOLVED

The current demo conservatively reserves SUPPORTED for independently complete reviewed evidence rather than issuing it automatically.

Evidence coverage is separate from the verdict. It counts completed checks, including source availability, reporting periods, comparable measurements, and independent scope verification.

It is not a probability that the claim is true.

The AI adapter has a narrow role

When configured, Gemini suggests ambiguities. It does not decide the verdict, invent sources, execute tools, or submit transactions.

The adapter uses:

A server-side API key.
A configured model rather than an assumed default.
Runtime validation of structured JSON.
Output and token limits.
Bounded attempts within an overall time budget.
Deterministic fallback.

The effective mode and fallback reason are recorded with the investigation. A “configured” integration flag alone cannot establish that a model successfully ran.

Live Gemini behavior was not part of the completed local validation, so the application does not claim otherwise.

Evidence Integrity Starts Before Blockchain

One of the most instructive defects appeared in deduplication.

An early normalization step removed punctuation. That made these passages appear identical:

Emissions were 1.2 tonnes.
Emissions were 12 tonnes.

Case folding introduced another scientific problem:

Energy use was 1 MWh.
Energy use was 1 mWh.

Those units are different.

The corrected implementation deliberately uses conservative, exact text deduplication. It normalizes Unicode and whitespace while preserving case, punctuation, signs, units, and negation.

const key = hash(
  excerpt
    .normalize("NFC")
    .replace(/\s+/g, " ")
    .trim()
);

Similar passages remain separate. The application no longer claims semantic near-duplicate detection.

This was a useful architectural lesson: normalization is a domain decision. A transformation that helps ordinary text matching can destroy scientific meaning.

We also corrected synthetic source passages so their classification explanations refer to details actually present in the excerpt. A synthetic label is disclosure, not a substitute for traceability.

Persistence: Simple Storage, Explicit Constraints

For the local demonstration, we chose a JSON repository rather than introducing a database server.

That keeps setup accessible, but it requires clear limits.

The local adapter now provides:

Runtime schema validation.
Aggregate and record-count limits.
Atomic file replacement.
File synchronization before replacement.
A previous validated backup.
A process-owner writer guard.
Checksum-verified backup and restore commands.

Finalized snapshots are copied separately from working case data. Later evidence additions do not rewrite those snapshots.

This is application-level immutability, not write-once storage. An actor with filesystem access can still alter files; independent hash verification is what makes changes detectable.

The optional Supabase adapter uses revision-based compare-and-swap updates to reject lost-update races. That implementation still requires separate validation with a live Supabase environment.

The lesson was not that JSON is universally sufficient. It was that a small demo benefits from a storage model whose constraints are explicit and tested.

Blockchain Auditing: Two Systems, One Difficult Failure Boundary

The Solidity registry stores minimal information:

An opaque case identifier.
A report version.
A 32-byte snapshot digest.
A registration timestamp.

Documents and full reports remain off-chain.

The contract restricts registration to its operator and rejects duplicate case versions and invalid inputs.

Before registration, the application serializes a finalized snapshot using application-defined canonicalization rules and calculates SHA-256 over the UTF-8 result.

Verification retrieves the actual registry record, recreates the snapshot digest, and compares them.

A matching result establishes integrity against that record. It does not establish that the evidence is authentic or the climate claim is correct.

The failure we initially missed

The difficult sequence was:

Transaction confirms on-chain
          ↓
Saving its local metadata fails
          ↓
User retries
          ↓
Contract rejects duplicate registration

Both individual systems behaved as designed. The combined workflow did not recover.

We fixed this with persisted operation states and reconciliation:

PENDING → BROADCAST → CONFIRMED
               ↘ UNAVAILABLE
               ↘ STALE
               ↘ CONFLICT

Before sending a transaction, the application checks the existing registry record.

An absent record can be registered.
A matching record can be reconciled with its confirmed receipt.
A conflicting digest stops the operation.
Historical metadata without a corresponding current registration is reported as stale or unavailable.

This also fixed another misleading behavior: after a chain reset, cached local metadata could previously produce a success response.

The corrected system checks the chain instead of treating its cache as proof.

Reliability: Keep External Waits Outside Storage Locks

The original mutation queue included network work.

That meant a stalled blockchain confirmation could delay unrelated case updates.

The revised approach keeps storage critical sections short:

Persist operation intent
          ↓
Release storage queue
          ↓
Perform bounded external work
          ↓
Re-enter queue
          ↓
Merge result into the intended version

Investigation updates use revision checks to avoid overwriting newer edits. Audit results are merged into the specific finalized version they belong to.

We tested this by pausing local mining. Anchoring reached its deadline while another case could still be finalized.

The important distinction is that a per-request RPC timeout is not an end-to-end operation deadline. The complete operation needs its own budget.

Security: Protect the Authority Behind the API

Keeping keys off the frontend was necessary, but insufficient.

The API can invoke an authorized registry operator. Without access control, a reachable client could exercise that authority indirectly.

Climate Court now has two access modes.

Local presenter mode

The custom Node server binds to loopback and checks the actual peer, Host header, and original forwarding headers before Next.js handles the request.

It adds a random process-private gateway proof. Local API access requires that proof and fails closed without it.

Shared operator mode

Shared mode requires HTTPS configuration and securely injected operator credentials. Sessions use signed, expiring cookies with:

HttpOnly
Secure
SameSite=Strict

Case reads, reports, mutations, reset controls, and blockchain actions require authorization.

Additional protections include server-only credential modules, sanitized API errors, secret scanning, staged-content checks, request budgets, and browser security headers.

PDF extraction runs in a separate process with a bounded heap, page/text limits, a deadline, and no inherited application credentials. This provides resource isolation; it is not an OS security sandbox.

Readiness, Observability, and Recovery

A health endpoint that always says “ok” is not a readiness check.

We separated:

Liveness: the process can answer.
Readiness: required configuration, storage, and dependencies are usable.

The demo preflight also performs a functional case read and checks the local registry and operator.

Operational events contain an operation name, request ID, outcome, allowlisted diagnostic code, and duration. Raw SDK errors, credentials, request bodies, and source documents are excluded.

Recovery is documented and executable. Backup restoration validates the manifest, stored structure, and finalized snapshot digests, while preserving replaced data for inspection.

Local report backups do not restore ephemeral blockchain history. The runbook makes that distinction explicit.

How Architectural Best Practices Helped

We used established frameworks as review lenses rather than claiming formal certification.

Principle	Concrete application
AWS Well-Architected reliability	Bounded operations, dependency readiness, reconciliation, tested restoration
OWASP access control	Authorization around report data and operator-backed actions
OWASP secrets and error handling	Server-only modules, secret checks, sanitized public errors
12-Factor configuration	Runtime configuration and optional backing-service adapters
SOLID separation of concerns	Independent services, repository boundary, extracted presentation modules
Google SRE principles	Failure injection, truthful status, operational budgets, recovery rehearsals
ISO/IEC 25010	Correctness, recoverability, maintainability, and measured resource behavior
NIST SSDF	Repeatable CI gates, dependency review, security regression tests
AI risk management	Narrow model authority, explicit uncertainty, provenance, bounded fallback

The most useful outcome was a prioritized list of small changes. None required an enterprise-scale rewrite.

What Went Well

The final local validation included:

34 passing automated tests.
HTTP and desktop/mobile browser workflows.
Browser upload, retry, and refresh failure paths.
Real transaction confirmation followed by local persistence failure.
Chain stalls, resets, and conflicting digests.
Backup, restore, restart, and operator-access checks.
Ten consecutive complete claim-to-verification rehearsals.

A bounded local resource rehearsal used 20 load cases, five 1,000-word sources per case, and three snapshots each.

After warm-up, across 20 measured iterations:

Measurement	Observed
Read latency p95	24 ms
Write latency p95	54 ms
Peak RSS	288 MiB

These are local observations, not hosted availability guarantees.

The production dependency audit reported zero vulnerabilities after patching Zod and PostCSS. A separate full-tree audit still identified development-tool advisories; their applicability and residual risks are documented rather than hidden.

What We Learned

The happy path is weak evidence of reliability. The most valuable tests interrupted the workflow between successful steps.

Retries are part of the architecture. An error message cannot compensate for an operation that is unsafe to repeat.

Truthful status is a correctness requirement. “Configured,” “registered,” “confirmed,” and “verified” describe different facts.

Scientific text needs conservative processing. Decimal points, signs, scope, units, and casing can change the meaning of evidence.

AI availability should not determine application availability. A narrow optional adapter made fallback straightforward.

A monolith can have strong boundaries. Separating responsibilities and shortening critical sections solved the demonstrated problems without multiplying infrastructure.

What Comes Next

The next useful capability is a human-reviewed evidence classification workflow, with stronger provenance and richer comparisons across reporting periods and emissions scopes.

Other planned work includes live validation of the optional Gemini and Supabase adapters, authenticated collaboration, and public-testnet integration.

Those are separate deployment and product scopes. The current evidence supports a controlled local single-operator demonstration—not a claim of public production readiness.

Climate Court’s goal remains consistent: help users follow the evidence, preserve uncertainty, and make the resulting investigation independently inspectable.

Repository: github.com/scha54/Climate-Court

From Vibe Coding to Demo-Ready: Hardening a React Application with the Twelve-Factor App Methodology

Sandeep Chakravartty — Sat, 24 Oct 2026 09:15:49 +0000

How I used software architecture principles, the Twelve-Factor methodology, security controls, automated testing, and immutable deployments to harden a Rapid Circularity Assessment calculator.

1. Introduction: The challenge with vibe-coded applications

Vibe coding has fundamentally changed how quickly we can translate ideas into working applications.

With AI-assisted development, we can move from a concept to a functioning prototype in hours rather than weeks. This is particularly valuable for experimentation, research applications, proof-of-concepts, and demonstrations.

However, there is a significant difference between an application that works on a developer's machine and one that is sufficiently reliable, secure, explainable, and reproducible for a professional demonstration.

AI-generated applications may work well along their intended happy paths but still have architectural weaknesses:

Limited separation of business logic and presentation
Unvalidated user inputs and browser storage
Inconsistent error handling
Uncontrolled dependencies
Missing automated testing
Environment-specific assumptions
Limited operational observability
Unrepeatable build and deployment processes

These weaknesses become particularly visible during demonstrations, when an unexpected input, browser refresh, deployment issue, or calculation inconsistency can undermine the credibility of the entire solution.

I encountered this engineering challenge while developing the Rapid Circularity Assessment (RCA) Calculator, a browser-based application for estimating material savings and additional environmental and worker outcomes associated with circular business models.

Rather than introducing an unnecessarily complex enterprise architecture, I used the Twelve-Factor App methodology as an architectural hardening framework, supplemented by security engineering, automated testing, deployment verification, and operational readiness practices.

This article explains the application architecture, the technology stack, the hardening decisions, and how the twelve factors were adapted to a predominantly client-side system.

GitHub repository: https://github.com/scha54/RCA-Calculator

Live application: https://rca-calculator.vercel.app

2. Understanding the RCA Calculator

The RCA Calculator is a research-oriented screening application designed to explore how circular economy interventions might reduce virgin textile consumption.

Users can model interventions such as extending product lifetimes, increasing garment reuse, improving textile collection and recycling, and reducing manufacturing waste.

The application provides the ability to:

Estimate annual virgin textile material savings.
Compare up to three assessment scenarios.
Evaluate material circularity across slowing, closing, and life-cycle strategies.
Explore environmental and worker-related outcomes.
Apply configurable uncertainty assumptions.
Conduct sensitivity analysis to identify influential parameters.
Visualize results through radar charts and sensitivity diagrams.
Export assessment results to Excel, JSON, Markdown, and printable reports.

An important characteristic of this application is that it is a screening model, not a certified Life Cycle Assessment (LCA) system.

The calculations support exploratory evaluation and decision-making. They do not establish independently audited environmental impact claims.

This distinction influenced the architecture. The application needed transparent calculations, explicit assumptions, validation, and traceable outputs rather than a complicated backend infrastructure.

3. Architecture: A modular, browser-first application

The deployed RCA Calculator follows a static-client, modular frontend architecture.

It does not require an application backend, shared database, authentication service, or server-side calculation engine.

Instead, the system separates presentation, domain calculations, scenario management, local persistence, reporting, and deployment responsibilities.

High-level architecture

                  User / Browser
                         |
                         v
                React Presentation
                         |
           +-------------+-------------+
           |             |             |
           v             v             v
      Assessment     Scenario       Results and
      Workflow       Management     Visualization
           |             |             |
           +-------------+-------------+
                         |
                         v
                TypeScript Domain
                 Calculation Engine
                         |
          +--------------+-------------+
          |              |             |
          v              v             v
     JSON Model      Sensitivity    Additional
     Definitions      Analysis       Outcomes
          |              |             |
          +--------------+-------------+
                         |
              +----------+----------+
              |                     |
              v                     v
       Browser Storage        Export Services
        (localStorage)      JSON / Excel / Print
              |
              v
        Portable Backup


              Delivery Architecture

          GitHub Source Repository
                    |
                    v
             GitHub Actions
                    |
          +---------+----------+
          |                    |
          v                    v
     Automated Tests     Security & Build
                            Validation
          |                    |
          +---------+----------+
                    |
                    v
             Vite Build
                    |
                    v
           Immutable dist/
           + release.json
                    |
           +--------+---------+
           |                  |
           v                  v
       Vercel CDN       Portable Node
                       Static Server

The architecture makes a deliberate trade-off: it prioritizes simplicity, reproducibility, privacy, and maintainability over features that would require centralized application state.

Separation of architectural responsibilities

The codebase is structured around identifiable functional boundaries.

RCA-Calculator/
|
+-- data/
|   +-- formulas.json
|   +-- parameters.json
|   +-- confidence.json
|   +-- benchmarks.json
|   +-- settings.json
|
+-- src/
|   +-- components/
|   +-- pages/
|   +-- engine/
|   |   +-- model.ts
|   |   +-- calculate.ts
|   |   +-- outcomes.ts
|   |
|   +-- export/
|   |   +-- excel.ts
|   |   +-- json.ts
|   |
|   +-- platform/
|   |   +-- diagnostics.ts
|   |
|   +-- App.tsx
|   +-- main.tsx
|
+-- tests/
+-- e2e/
+-- scripts/
+-- docs/
+-- .github/workflows/
|
+-- package.json
+-- package-lock.json
+-- vercel.json
+-- vite.config.ts

This structure serves several architectural purposes.

Presentation remains separate from calculation logic. React components manage user interaction, navigation, and visualization, while domain logic is implemented in TypeScript modules.

Model definitions are externalized into version-controlled JSON files. Parameters, formulas, confidence bands, and reference benchmarks are independently identifiable.

Export functionality is isolated. Generating an Excel workbook does not require embedding workbook-generation logic inside the assessment screens.

Platform responsibilities are explicit. Diagnostics, deployment configuration, build verification, and runtime serving are distinguishable from domain calculations.

This separation is important when hardening an AI-assisted application because it makes code reviews and automated testing more focused.

Instead of reviewing a large, tightly coupled component, we can review specific architectural responsibilities.

4. Technology stack

The RCA Calculator uses a relatively small but purposeful technology stack.

Layer	Technology	Responsibility
UI framework	React 19	Component-based interactive interface
Programming language	TypeScript 5.8	Type safety and maintainable domain logic
Build system	Vite 6	Development tooling and optimized production bundles
Styling	Tailwind CSS 4	Responsive presentation and design consistency
Visualization	Recharts 3	Results and analytical charts
Workbook generation	ExcelJS 4.4	Client-side Excel report generation
Persistence	Browser localStorage	Local assessment state
Unit testing	Vitest 5	Model and utility verification
Browser testing	Playwright	End-to-end workflow verification
Accessibility testing	axe-core with Playwright	Automated accessibility checks
Runtime tooling	Node.js 24 / npm 11	Reproducible builds and portable serving
CI	GitHub Actions	Automated validation and release artifact generation
Hosting	Vercel	Static application delivery
Version control	Git / GitHub	Source control and release traceability

Python also appears in the repository as a utility for creating model data. It is not part of the deployed browser runtime.

An important architectural decision was to avoid introducing technologies without a clear application requirement.

For example, adding PostgreSQL, Redis, message queues, or Kubernetes would not automatically make this calculator more robust. For the current single-user browser workflow, these technologies would increase operational responsibilities without providing proportional value.

The architecture follows a practical principle:

Use the minimum system complexity required to satisfy the application's functional and non-functional requirements.

5. Designing a reliable domain calculation engine

For a scientific screening application, the calculation engine is one of the most important architectural components.

A visually polished interface is of limited value if the underlying model is inconsistent or cannot be independently verified.

The RCA Calculator defines model parameters and mathematical expressions separately from the presentation layer.

The calculation engine reads those definitions, validates scenario inputs, evaluates formulas, and produces structured results.

For example, the baseline virgin textile demand is calculated as:

Baseline Virgin Demand =
    Items Sold
  × Average Garment Weight
  × (1 - Collection Rate × Recycling Yield)
  / 1000

The division converts kilograms into tonnes.

The application then calculates contributions from several circularity interventions and derives total material savings and residual virgin demand.

Restricted formula evaluation

One useful hardening decision was implementing a restricted arithmetic parser instead of evaluating expressions as JavaScript.

The parser accepts a controlled set of operations, numeric literals, named variables, parentheses, and MIN/MAX functions.

It does not execute arbitrary JavaScript from model definitions or imported scenarios.

This creates an important security boundary between externally represented calculation data and executable application code.

Input and model validation

The domain model also validates incoming scenarios.

Validation includes:

Scenario schema version and structural integrity
Supported geographic regions
Numeric bounds and finite numeric values
Valid confidence selections
Consistency of uncertainty bands
Required model assumptions
Qualitative checklist and risk-note structures

Scenario imports are additionally subject to a 1 MiB size limit before parsing.

This protects against malformed inputs and reduces the risk of accidental excessive memory consumption.

Scientific integrity as an architectural quality attribute

A particularly valuable hardening feature is the separation between calculating draft results and authorizing formal report generation.

Users can explore results while refining assumptions. However, finalized reports require confirmation of material assumptions such as substitution and rebound, along with source information for enabled additional outcome modules.

Editing relevant model assumptions invalidates those confirmations.

This is not merely a UI feature.

It is an example of implementing domain-specific quality controls directly into the application's architecture.

It helps prevent unreviewed assumptions from silently becoming apparently authoritative outputs.

6. Applying the Twelve-Factor App methodology

The Twelve-Factor App methodology was originally developed for software-as-a-service applications, especially systems with server-side processes and backing services.

It would be inappropriate to apply every factor literally to a static browser application.

Instead, I used the methodology to assess each architectural concern against the RCA Calculator's actual deployment model.

The key question was not:

How can this application be made to look like a conventional cloud-native service?

It was:

How can each applicable Twelve-Factor principle improve the reliability, portability, security, and operational readiness of this application?

Factor I — Codebase: One codebase, multiple deployments

The first factor requires one codebase tracked in version control, with multiple deployments derived from it.

The RCA Calculator uses a single GitHub repository as the source of truth.

During hardening, unnecessary tracked npm cache content was identified and removed from the Git index. Ignore rules exclude generated output, local environment files, caches, and deployment metadata.

The intended result is a cleaner source repository where build outputs are generated rather than manually maintained.

This supports:

More predictable code reviews
Cleaner continuous integration
Release traceability
Consistent preview and production builds

The existing Git history was not rewritten to eliminate historical cache objects.

Factor II — Dependencies: Explicit and reproducible dependency management

A common source of demo failures is inconsistent dependency installation.

A prototype may work locally because packages were installed incrementally or differ from the versions available in a clean environment.

The RCA Calculator addresses this using package.json, package-lock.json, a declared Node version, and a recorded npm version.

The application specifies Node.js 24 and npm 11, with npm 11.9.0 recorded as its package manager.

A clean installation uses:

npm ci --include=dev

Unlike a general dependency update, npm ci installs from the committed lockfile and rejects incompatible dependency manifests.

Dependency hygiene was also incorporated into CI.

npm run audit

The audit command fails on high- and critical-severity findings.

During hardening, unused direct dependencies were removed, and Vitest was upgraded to address serious toolchain advisories.

One moderate ExcelJS transitive dependency advisory involving UUID remained documented, with its usage and risk boundary explicitly analyzed rather than silently suppressed.

Lesson: Dependency hardening requires reproducibility, inventory, risk assessment, and continuous review—not simply installing the latest versions of everything.

Factor III — Config: Separate configuration from code

Twelve-Factor applications should keep deployment-specific configuration outside their source code.

For the RCA Calculator, there are no backend credentials, database connection strings, or private API keys to configure.

The browser application is designed to operate without application environment variables.

The portable Node server supports environment configuration:

PORT=3000
HOST=0.0.0.0
SHUTDOWN_TIMEOUT_MS=10000

The build also supports revision metadata through environment-provided values such as RELEASE_REVISION and Vercel's VERCEL_GIT_COMMIT_SHA.

An important distinction is maintained between configuration and domain model data.

Mathematical formulas and model assumptions belong in version-controlled domain definitions because changing them changes the behavior and interpretation of the assessment.

They are not interchangeable deployment settings.

Another important frontend security consideration is that Vite client-side configuration is not secret storage.

Values embedded into a public JavaScript bundle must be treated as publicly accessible.

Factor IV — Backing services: Explicit service dependencies

A conventional cloud application may rely on a database, cache, or external message broker.

The RCA Calculator has no such server-side backing-service dependency.

Assessment state is stored locally in the user's browser using localStorage.

This substantially reduces deployment complexity and avoids introducing a centralized store for user-generated assessment data.

However, browser storage is not equivalent to a durable, account-backed database.

Its limitations are explicitly documented:

Data is associated with a browser and origin.
Clearing browser storage can delete assessments.
Assessments do not automatically synchronize between devices.
Users must export JSON backups when portability is required.

This is an intentional product constraint, not something that should be hidden behind a claim of database-like durability.

If collaboration, authentication, or cross-device persistence becomes necessary, a separate backing service would need to be designed.

Factor V — Build, release, run: Immutable deployments

This was one of the most significant parts of the architecture hardening.

In loosely managed applications, the production server may install dependencies, compile code, or modify files during startup.

That makes it difficult to know whether the deployed application is identical to what was tested.

The RCA Calculator separates build, release verification, and runtime serving.

Source Code
    |
    v
npm ci
    |
    v
TypeScript Check + Vite Build
    |
    v
dist/
    |
    v
release.json
    |
    v
Integrity Verification
    |
    v
Tested Release Artifact
    |
    v
Deployment / Serving

The build command is:

npm run build

It performs TypeScript checking, builds the application, and generates release metadata.

The generated release.json contains information including the application version, source revision, artifact identifier, and SHA-256 checksums of the release files.

Verification runs with:

npm run check:release

The portable production server verifies the existing artifact before serving it.

Crucially, the runtime does not rebuild the application.

This gives deployments a stronger identity: the released files can be checked against the exact artifact that passed validation.

The checksum manifest is an integrity mechanism, not a digital signature proving the identity of a publisher.

Factor VI — Processes: Stateless application serving

The deployed serving layer is stateless.

The Node server serves an immutable directory and does not maintain user assessments, sessions, or mutable application state.

Calculations and editing occur inside the browser.

This means multiple serving instances can deliver the same release artifact without synchronizing user sessions.

The architecture avoids sticky-session requirements and server-side state recovery concerns.

Browser-local data remains a separate responsibility.

This is an example of how stateless service architecture can coexist with client-side state.

Factor VII — Port binding: Self-contained runtime behavior

Vercel hosts the static application and manages HTTP delivery.

For environments requiring a standalone process, the repository also contains a portable Node.js server.

The server binds to its configured host and port:

PORT=3000 HOST=0.0.0.0 npm start

It also exposes:

GET /healthz

The health response reports runtime readiness and the current artifact identifier.

This endpoint is specific to the portable Node server. It is not automatically an application endpoint on the Vercel static deployment.

For Vercel, the operational documentation recommends using release metadata and live endpoint checks to verify the deployed version.

The portable server should be placed behind an HTTPS-terminating proxy when exposed to end users.

Factor VIII — Concurrency: Scaling without shared state

The application does not require a distributed calculation cluster.

Its analytical calculations are performed in each user's browser, while static assets can be distributed through a CDN.

For standalone hosting, independent Node processes can serve the same immutable build.

Operational tests exercise multiple server instances using the same release artifact.

This demonstrates independence of serving instances, but it does not establish a particular requests-per-second capacity or geographic latency guarantee.

Those require separate load testing and hosting-level measurements.

The architectural benefit is that horizontal serving does not introduce shared mutable state coordination.

Factor IX — Disposability: Predictable startup and graceful shutdown

A service should start predictably and shut down cleanly.

The portable Node server verifies its release files before accepting traffic.

It handles SIGTERM and SIGINT, stops accepting new work, and allows active responses to drain within a configurable timeout.

For example:

SHUTDOWN_TIMEOUT_MS=10000

If the shutdown grace period expires, remaining connections are terminated.

The application also implements browser-side recovery.

React error boundaries provide a fallback interface if rendering fails. Users can reload the application or download a backup of saved assessments.

This is particularly important when a deployment removes a JavaScript chunk that an older browser session is still attempting to load.

Preserving previous immutable deployments and their hashed assets helps reduce such failures.

The result is a layered recovery model covering both the serving process and the browser interface.

Factor X — Dev/prod parity: Test the production build

A frequent weakness in prototype development is testing only the development server.

Vite's development environment is not identical to the compiled, security-constrained production application.

The RCA Calculator addresses this with browser tests that run against the actual production build served by the portable Node runtime.

Playwright tests interact with the application as users would.

They cover assessment workflows, persistence, imports, exports, mobile behavior, and accessibility checks.

This matters because a development build may work while a production Content Security Policy blocks a library or a lazily loaded component.

By validating the production artifact and its response headers, the tests exercise a more representative deployment.

There is still a boundary: passing local production-server tests does not prove that Vercel's live CDN configuration, TLS, and project settings are correct.

Those require post-deployment verification.

Factor XI — Logs: Structured, privacy-conscious observability

Operational diagnostics are essential when hardening an application.

The portable Node server emits structured JSON events to standard output.

Request events include information such as:

{
  "event": "http_request",
  "requestId": "generated-request-id",
  "method": "GET",
  "route": "asset",
  "status": 200,
  "durationMs": 4,
  "artifactId": "release-artifact-id"
}

The server intentionally avoids logging scenario content, query strings, request bodies, and assessment details.

Browser diagnostics also use predefined event codes.

For example, a render failure can produce an event containing its type, application version, and revision without exposing the user's model inputs.

These logging decisions are important because the application may hold commercially sensitive assessment assumptions.

However, browser console messages are not automatically collected into a central monitoring platform.

Operational logging therefore has two distinct boundaries:

Host-managed access and runtime logs.
Local browser diagnostics that would need an explicitly designed collection mechanism for remote monitoring.

Retention, access controls, alerting, and centralized observability remain hosting responsibilities.

Factor XII — Admin processes: Controlled one-off operations

Traditional applications may require administrative commands for migrations, data repair, and database maintenance.

The RCA Calculator does not have server-side migrations or account administration.

Its one-off operational commands include release verification, dependency audits, and scenario validation.

For example:

npm run validate:scenario -- ./assessment.json

This validates a local assessment using the application's model rules.

The validator can identify invalid records without uploading the user's assessment or modifying the source file.

The principle is straightforward: operational utilities should use the same validated codebase as the application and should behave predictably.

7. Security hardening beyond the Twelve-Factor methodology

Although Twelve-Factor is a useful architecture framework, it is not a complete security standard.

For a browser application, additional controls are necessary.

Content Security Policy

The Vercel configuration defines a Content Security Policy that restricts script loading and network connections to the application's origin.

Key directives include:

default-src 'self'
script-src 'self'
connect-src 'self'
object-src 'none'
frame-ancestors 'none'
form-action 'none'

This limits several classes of unwanted browser behavior.

The configuration still permits inline styles because of the application's React and chart-rendering requirements, but it does not permit inline scripts or eval.

HTTP response security headers

Additional headers include:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
Permissions-Policy:
  camera=(), microphone=(),
  geolocation=(), payment=()

These controls reduce unnecessary browser capabilities and help mitigate framing and content interpretation risks.

Static-server restrictions

The portable Node server implements defensive serving behavior.

It rejects unsupported HTTP methods, invalid paths, hidden-file access, and attempts to escape the designated release directory.

Symbolic links are also rejected during release verification.

Only intended static resources are exposed.

Defensive browser persistence

An additional hardening feature appears in the way saved scenarios are restored.

If some browser records are malformed, the application attempts to retain valid records instead of discarding the entire dataset.

Automatic saving is paused when invalid records are detected, preventing the application from silently overwriting the original storage contents.

The user is offered an explicit recovery path.

This illustrates a useful defensive design principle:

When recovering from invalid state, preserve the original evidence rather than automatically destroying it.

8. Performance engineering through selective loading

Demo readiness also depends on responsiveness.

An application that works correctly but takes too long to initialize can create an unreliable demonstration experience.

The RCA Calculator uses React lazy loading and Vite's code-splitting capabilities.

The results screen, scenario comparison interface, and export screen are loaded on demand.

Excel generation is also deferred until the user requests it.

For example, the application uses a dynamic import for the workbook generation module:

const { exportScenarioToExcel } =
  await import("../export/excel");

await exportScenarioToExcel(scenario);

This prevents the Excel generation library from unnecessarily increasing the initial application payload.

The repository also defines an initial JavaScript bundle budget of 450,000 bytes.

The budget is checked automatically:

npm run check:bundle

The check traverses the initial JavaScript dependency graph using the Vite build manifest and fails if the budget is exceeded.

This is an effective example of turning a non-functional architecture requirement into an automated build gate.

The ExcelJS deferred bundle remains relatively large, approximately 947 kB before compression according to the repository documentation, but it is not part of the initial load.

That trade-off is visible rather than hidden.

9. Establishing confidence through automated testing

Perhaps the most important transition from prototype to demo-ready software is moving from informal testing to repeatable evidence.

The RCA Calculator has several testing layers.

Unit and domain tests

Vitest is used to test calculation behavior, including reference arithmetic, model validation, uncertainty aggregation, sensitivity analysis, and export correctness.

These tests help ensure that changes to components or model assumptions do not unexpectedly change calculations.

End-to-end browser testing

Playwright validates real browser workflows.

This includes scenario management, report generation, browser persistence, imports, exports, and responsive behavior.

Accessibility checks

The testing stack integrates axe-core with Playwright to identify serious accessibility violations.

Automated accessibility validation is valuable, but it does not replace human keyboard-navigation and screen-reader testing.

Operational verification

The repository contains Node operational tests for serving behavior, security headers, runtime lifecycle, and release integrity.

This is especially useful for verifying the architectural requirements that do not fit naturally into React unit tests.

Continuous integration

GitHub Actions runs the validation process on pushes and pull requests.

The pipeline follows this pattern:

Checkout Repository
        |
        v
Setup Node.js 24
        |
        v
npm ci --include=dev
        |
        v
Dependency Audit
        |
        v
Unit Tests
        |
        v
Production Build
        |
        v
Bundle Budget Check
        |
        v
Release Integrity Check
        |
        v
Operational Tests
        |
        v
Playwright Browser Tests
        |
        v
Retain Tested Artifact

The resulting static artifact is retained by CI, while failed browser tests can provide diagnostic traces.

Importantly, the workflow validates and retains the release artifact; it does not automatically publish the application.

Separating validation from promotion provides an additional opportunity for controlled deployment approval.

10. Architecture hardening as measurable engineering controls

A useful lesson from this exercise is that architecture reviews become more valuable when principles translate into verifiable controls.

Rather than treating architecture as a collection of diagrams and recommendations, each significant quality requirement can be associated with implementation evidence.

Architecture quality	Hardening mechanism	Evidence
Reproducibility	Locked dependencies and pinned runtime	`package-lock.json`, `.nvmrc`
Maintainability	Separation of UI, domain, and export logic	`src/` modules
Correctness	Domain validation and unit tests	`model.ts`, `tests/`
Security	CSP, input validation, server restrictions	`vercel.json`, serving code
Performance	Lazy loading and size budgets	Vite build and bundle checker
Reliability	Error boundaries and recovery	`ErrorBoundary.tsx`
Deployability	Immutable artifacts and integrity checks	`release.json` and verification scripts
Operability	Health checks and structured logs	Portable Node server
Testability	Unit, operational, browser, and accessibility tests	Vitest, Playwright, GitHub Actions
Data protection	Local persistence and explicit backup paths	Scenario management and JSON export

This is the point where architectural maturity becomes observable.

The application is not considered hardened merely because someone has documented good intentions.

It is hardened to the extent that those intentions are represented by controls, tests, and operational procedures.

11. What the hardening achieved

The architectural work produced several meaningful improvements.

First, a more deterministic build and release process. By using a locked toolchain and immutable release files, the deployed artifact can be identified and checked independently of a developer's local environment.

Second, better separation of concerns. The domain engine, model data, user interface, exports, and deployment tooling have clearer boundaries, making it easier to inspect and change the application.

Third, stronger failure handling. Malformed scenario records, unavailable local storage, render failures, and shutdown events are handled more deliberately.

Fourth, an improved browser security posture. Explicit response headers, restricted formula execution, input validation, and defensive static serving reduce avoidable exposure.

Fifth, automated quality gates. Tests, dependency audits, release verification, and bundle checks help catch issues before a demonstration or deployment.

Finally, reduced operational complexity. By preserving a static-client architecture, the application avoids unnecessary infrastructure while retaining clear pathways for future evolution.

These are architectural and operational improvements, rather than measured claims about runtime speed, service uptime, or production traffic capacity.

12. What remains outside demo hardening

Demo hardening is not equivalent to claiming unrestricted production readiness.

The repository documents several important limits.

The application is not a certified environmental assessment engine. Domain review and independent model assurance would be needed before using its outputs as formally assured scientific claims.

Browser-local persistence does not provide enterprise-grade durability, centralized backup, or account synchronization.

Live Vercel deployment configuration must be verified after release. Repository declarations do not prove that hosting-level controls, monitoring, DNS, TLS, and deployment permissions are correctly configured.

The documented moderate transitive dependency advisory still requires continued monitoring.

And while CI provides substantial automated coverage, performance capacity testing, human accessibility review, and organizational risk acceptance are separate activities.

This distinction is central to responsible engineering.

A successful hardening effort should make the system's capabilities clearer without hiding its limitations.

13. Lessons learned: From rapid prototyping to architecture discipline

This project reinforced several engineering lessons.

Architecture principles are more important than architectural fashion

A system does not need microservices, containers, distributed caches, and multiple databases to qualify as well architected.

Architecture quality is better judged by how effectively a design meets its actual requirements and controls its risks.

Twelve-Factor is a methodology, not a technology checklist

The twelve factors helped structure the review around reproducibility, configuration, deployment, statelessness, operational behavior, and test parity.

Applying them intelligently was more useful than forcing the application into an inappropriate backend architecture.

Automated tests should protect both functionality and architecture

Calculation tests protect the scientific model.

Browser tests protect user journeys.

Operational tests protect runtime behavior.

Security and bundle checks protect non-functional quality requirements.

Together, these give stronger evidence than relying on manual UI testing alone.

Immutability improves confidence in demonstrations

Being able to identify and verify the exact artifact being served reduces uncertainty during deployment and rollback.

A demo should not depend on a server silently rebuilding code or resolving different dependencies at startup.

Defensive design matters as much as the happy path

Applications are often judged by what happens when something goes wrong.

Graceful error screens, preserved browser data, explicit export errors, bounded inputs, and predictable shutdown behavior all contribute to trust.

AI can accelerate implementation, but engineering accountability remains essential

AI-assisted development makes generating software easier.

It does not remove the need to establish architectural boundaries, validate assumptions, test calculations, manage dependencies, and understand operational risks.

The transition from vibe-coded prototype to demo-ready application is therefore not simply a refactoring exercise.

It is the process of turning experimental code into a system with explicit, testable engineering properties.

14. Conclusion

The RCA Calculator demonstrates that a relatively lightweight browser application can benefit significantly from formal architecture hardening.

By applying the Twelve-Factor App methodology pragmatically, separating domain logic from presentation, enforcing dependency reproducibility, implementing immutable releases, strengthening browser security, and introducing automated validation, the application has a more disciplined foundation for demonstrations and further development.

The most important architectural decision was not adding infrastructure.

It was making the existing architecture reliable, understandable, testable, and operationally explicit.

That is a useful approach for anyone developing AI-assisted proof-of-concepts, research tools, internal applications, or early-stage products.

Vibe coding can help us reach a working prototype quickly.

Software engineering discipline is what helps us demonstrate it with confidence.

Source code and technical references

Project repository: https://github.com/scha54/RCA-Calculator

Live application: https://rca-calculator.vercel.app

Twelve-Factor architecture assessment: https://github.com/scha54/RCA-Calculator/blob/master/docs/TWELVE_FACTOR.md

Operations runbook: https://github.com/scha54/RCA-Calculator/blob/master/docs/OPERATIONS.md

Calculation methodology: https://github.com/scha54/RCA-Calculator/blob/master/docs/METHODOLOGY.md

Release verification documentation: https://github.com/scha54/RCA-Calculator/blob/master/docs/RELEASE.md

The Twelve-Factor App methodology: https://12factor.net/

This article describes the repository architecture and documented hardening controls as reviewed on October 24, 2026. The project remains a screening and demonstration application; deployment assurance and scientific certification are separate considerations.

What practices do you use to move AI-generated prototypes toward demo-ready or production-ready software? I'd be interested to hear how others are applying architecture principles without introducing unnecessary complexity.

Memory Lane AI — Privacy-First Family Memory Storyteller 📖✨

Sandeep Chakravartty — Thu, 15 Oct 2026 19:19:49 +0000

Every family possesses an irreplaceable archive of oral lore: the story of how grandparents migrated during tough times, the secret spices behind a holiday stew, or childhood summers spent climbing mango trees. Yet, most of these memories remain trapped in fragile photo boxes, disjointed voice memos on old phones, or fading recollections.

Commercial "AI biography" apps have attempted to address this, but they introduce a severe compromise: they require you to upload your family’s most intimate photographs, private recordings, and personal names to closed, cloud-hosted LLM services. For families protective of their privacy—or those preserving memories for elderly relatives—giving proprietary third-party servers perpetual access to family data is an absolute dealbreaker.

Memory Lane AI solves this problem by combining 100% local-first data sovereignty with open-source, on-device AI.

What I Built
Memory Lane AI is a local-first web application that helps families capture, organize, transcribe, and craft oral histories and heirloom photographs into timeless storybooks and archival, downloadable PDFs—with zero personal data leaving the user’s computer.

┌────────────────────────────────────────────────────────────────────────┐
│ Memory Lane AI Architecture │
├────────────────────────────────────────────────────────────────────────┤
│ [ React 19 + TypeScript + Vite 8 Frontend ] │
│ ├─ 15 Archival Screens (Vault, Timelines, Audio Recorder, Wizard) │
│ ├─ IndexedDB (Dexie.js) ──► 100% On-Device Photos, Audio & Records │
│ └─ jsPDF & html2canvas ──► High-Resolution Archival Storybook PDFs │
│ │ │
│ (Local HTTP / CORS) │
│ ▼ │
│ [ Python 3.14 FastAPI Microservice (localhost:8000) ] │
│ ├─ Modular Whisper Adapter ──► faster-whisper / openai-whisper (CPU) │
│ └─ Modular Ollama Adapter ──► Local LLMs (Llama 3, Mistral, Qwen) │
│ │ │
│ (Automatic Fallback) ───┴───► [ Client-Side Grounded Engine ] │
└────────────────────────────────────────────────────────────────────────┘
The 15-Screen Archival Suite
Welcome & Onboarding: Privacy manifest, local storage breakdown, and one-click demo archive loader.
Dashboard: Archival metrics, memory carousel, family members shelf, and active storybooks.
Memories Library: Filter by media type (photo, audio, text, mixed), people, tags, and date range.
Memory Details: Lightbox viewer, audio player with animated waveform, dual transcript viewer, and cited stories.
Add / Edit Memory: Multi-photo upload with instant previews, audio attachments, and date precision selectors (Exact, Month, Year, Approximate, Unknown).
People Directory: Family roster with relationship tags, birth/death years, and memory counters.
Person Profile & Timeline: Chronological, interactive life timeline for any family member.
Places & Events: Geographical clustering and milestones across family journeys.
Audio Recording & Transcription: In-browser microphone recorder with live VU level meter, timer, and transcription runner.
AI Story Creator Wizard: Multi-step wizard selecting source memories, tone (Warm & nostalgic, Simple & conversational, Documentary & factual, Child-friendly, Memoir style), and prompt constraints.
Story Editor: Section-by-section narrative editor with source memory citations and uncertainty tags.
Storybooks & Chapters: Book manager, chapter reordering, cover photo selection, and thematic styling.
Storybook Preview & Export: Paginated book preview with high-resolution PDF exporter.
Global Search: Instant multi-field search across titles, captions, transcripts, and tags.
Settings & Sovereignty: Live navigator.storage quota meter, AI backend connectivity status, full JSON backup export, and safe restore.
Who Would Pay For It? (The Side Hustle Opportunity)
Memory Lane AI was built with a viable, multi-tiered monetization strategy tailored for personal historians and privacy-conscious families:

Boutique Family Biography & Oral History Agency:
Target: High-net-worth families, adult children recording aging parents, and estate planners.
Offering: Professional memory capture sessions. Armed with Memory Lane AI running entirely on a local laptop, an oral historian visits elderly family members, records high-fidelity audio, imports family albums, generates grounded chapters with local open-weight models, and delivers heirloom hardcover books printed from the exported PDFs.
Price Point: $500 – $2,500 per completed family storybook.
Turnkey Archival Software for Senior Living & Memory Care Facilities:
Target: Assisted living centers, memory care communities, and hospice providers.
Offering: An on-premise, HIPAA-compliant memory vault. Because zero personal data, medical details, or elder voices leave the building, care facilities can safely capture residents' life stories for therapeutic reminiscence therapy and family keepsakes.
Price Point: $99 – $199/month per facility license.
Print-on-Demand Keepsake Integration:
Offering: Direct export pipeline from the application's structured PDF engine to custom photo-book printers (e.g., Blurb, Gelato) with built-in affiliate or print markups.
Code
The complete source code for Memory Lane AI is available under an open-source license:

👉 GitHub Repository: https://github.com/scha54/Hactoberfest-Hackathon-Week-2

Grounded AI Story Generation via Local Ollama To eliminate hallucinations (such as inventing relatives, dates, or events not present in the family's oral notes), the backend sends a strict JSON schema prompt to the local Ollama instance:

python

backend/app/adapters/ollama_story.py

class OllamaStoryAdapter(AIStoryAdapter):
"""
Integrates with local Ollama LLMs (Llama 3, Mistral, Qwen, etc.).
Uses a strictly grounded prompt to prevent hallucinations and formats output as JSON.
Gracefully falls back to MockStoryAdapter if Ollama is unreachable.
"""
async def generate_story(self, request: StoryGenerationRequest) -> StoryGenerationResponse:
system_prompt = (
"You are a family memory archivist and biographer. Your task is to write a warm, beautifully structured "
"family storybook chapter strictly grounded in the memories, transcripts, captions, and names provided.\n\n"
"CRITICAL CONSTRAINTS:\n"
"1. ONLY use details, places, names, and events explicitly provided in the user prompt.\n"
"2. DO NOT hallucinate dates, relatives, fictional drama, or unseen events.\n"
"3. If any detail is uncertain, approximate, or missing, add a note in the 'uncertainties' list.\n"
"4. Respond strictly with a valid JSON object matching the schema."
)
payload = {
"model": self.model,
"messages": [
{"role": "system", "content": system_prompt},
{"role": "user", "content": json.dumps(user_content, ensure_ascii=False)}
],
"stream": False,
"format": "json"
}
async with httpx.AsyncClient(timeout=45.0) as client:
res = await client.post(f"{self.base_url}/api/chat", json=payload)
# Parses sections, source citations, and uncertainty flags...

Local-First Client Persistence (Dexie.js & IndexedDB) All audio recordings, binary photo blobs, people profiles, and books are stored entirely within the client's browser IndexedDB:

typescript
// frontend/src/db/index.ts
import Dexie, { type Table } from 'dexie';
import type { Memory, Person, Story, Storybook, AppSettings } from '../types';
export class MemoryLaneDB extends Dexie {
memories!: Table;
people!: Table;
stories!: Table;
storybooks!: Table;
settings!: Table;
constructor() {
super('MemoryLaneAI_DB');
this.version(1).stores({
memories: 'id, title, datePrecision, place, createdAt, updatedAt, *tags, *peopleIds',
people: 'id, fullName, relationship, birthYear, deathYear, createdAt, *tags',
stories: 'id, title, tone, status, createdAt, updatedAt, *sourceMemoryIds',
storybooks: 'id, title, createdAt, updatedAt',
settings: 'id'
});
}
}
How I Built It
Memory Lane AI was engineered from the ground up using open-source AI models, open-source frameworks, and local-first browser storage:

Component Technology Role
Local LLM Engine Ollama (http://localhost:11434) Open-weight models (Llama 3, Mistral, Qwen 2.5, Phi-3) executing on-device inference via structured JSON mode.
Speech Recognition faster-whisper / Whisper Quantized (int8) automatic speech recognition running locally on CPU/GPU for transcribed oral recordings.
Backend API FastAPI + Pydantic + Uvicorn Python 3.14 asynchronous microservice exposing lightweight endpoints (/api/health, /api/capabilities, /api/stories/generate, /api/transcribe).
Frontend Framework React 19 + TypeScript (Strict) Component tree with 15 dedicated views, client-side routing, and responsive tactile layout.
Styling & Design Tokens Vanilla CSS + Archival Tokens Warm ivory backgrounds (#FAF7F2), charcoal espresso typography (#2C2523), terracotta accents (#C86D51), and serif headings.
Persistence Engine Dexie.js (IndexedDB) Multi-gigabyte browser-local storage holding binary blobs, audio tracks, and relational metadata.
PDF Generation jsPDF + html2canvas Automated typesetting engine producing multi-page, print-ready PDF storybooks with custom borders, dedications, and source citations.
Two-Tier Graceful Degradation Architecture
A core engineering requirement was that the app must never fail or lock the user out if the AI backend is unreachable.

Tier 1 (Full Local AI): If Ollama and FastAPI are running on localhost:8000, full speech-to-text with Whisper and grounded LLM generation are enabled.
Tier 2 (Client-Side Fallback): If running completely offline or without Python, the frontend automatically switches to a deterministic client-side story compiler (generateClientGroundedStory) and an oral history transcription simulator. Users can still record voice memos, create memories, manage people, assemble chapters, and export PDFs without any backend running.
Why Does Open Innovation Matter?
Open innovation is essential for projects involving personal human stories and family heritage:

Family Intimacy and Data Sovereignty: Closed AI services (OpenAI, Anthropic, Google Cloud) operate on multi-tenant infrastructure where inputs may be logged, reviewed by human moderators, or used for model training. Handing over high-resolution pictures of one's children, voice recordings of an ailing grandparent, or personal family triumphs to a closed commercial cloud compromises privacy. Open-weight models running on Ollama restore complete sovereign ownership: no packets cross the wire.
Permanence and Digital Longevity: Family archives must survive for decades. Closed APIs frequently deprecate endpoints, change pricing tiers, alter moderation policies, or terminate operations entirely. Open-source models and open standards (such as IndexedDB and client-generated PDFs) guarantee that an archive created today remains accessible decades from now, independent of any corporate roadmap.
Predictable Unit Economics: For a family historian or side-hustle biographic agency, per-token API fees can fluctuate wildly when transcribing hours of raw audio and synthesizing multi-chapter books. With open-weight models (Llama 3, Whisper), inference costs are flat: zero API bills, regardless of how many stories are preserved.
Retrospective: What Went Well, What Did Not, and Lessons Learned
What Went Well
Strictly Grounded Prompting: Constraining Ollama to a validated JSON schema with explicit sourceMemoryIds and an uncertainties array completely eliminated fabricated dates and fictitious relatives.
Robust Local Storage via Dexie.js: Storing large binary photo Blobs and WebM audio files directly in IndexedDB provided snappy, offline-first performance without needing any external database servers.
Automated Verification: The Python backend achieved 100% test coverage across all endpoints (pytest passing 4/4), and the React frontend passed strict oxlint checks with 0 warnings and 0 errors, accompanied by a clean TypeScript build.
What Did Not Go Well
Audio Codec Cross-Browser Fragmentation: The native browser MediaRecorder API defaults to audio/webm;codecs=opus on Chromium browsers, but Whisper expects raw audio or WAV streams. We had to ensure temporary file conversion and fallback handling in the Python adapter.
Large Production Bundle Size: Vite's production build reported a warning on the main chunk (dist/assets/index-BggqEAK5.js at ~1.29 MB). This was caused by statically bundling heavy client-side libraries (jspdf and html2canvas) into the main entry point rather than lazily loading them via dynamic import().
Open-Weight Model Variance: While Llama 3 and Qwen 2.5 adhered closely to the JSON formatting instructions, smaller parameter models (e.g., 1B–3B models) occasionally enclosed their outputs in markdown fences (json ... ) or omitted required uncertainty arrays. We implemented custom JSON extraction logic to handle these edge cases cleanly.
Lessons Learned
AI as an Enhancement, Not a Prerequisite: Structuring the software so that every core feature (data entry, timeline organization, chapter editing, PDF compilation) works 100% offline without AI creates a rock-solid, resilient application.
Transparent Storage Drives User Confidence: Providing a real-time storage quota meter and full one-click JSON backup/restore in the UI fundamentally transformed user trust. When users can see that their photos and audio are stored strictly on their physical machine, their willingness to record genuine, intimate memories increases dramatically.

Preserving Grandma's Recipes & Stories: Building a 100% Private, Source-Grounded Family Cookbook with Open-Source AI

Sandeep Chakravartty — Sun, 04 Oct 2026 18:37:50 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

Every family has a treasure trove of secret recipes, culinary tips, and cherished memories. But for most of us, these aren't written down in neat cookbooks or standardized digital apps—they are hidden inside informal WhatsApp voice messages, spoken anecdotes over dinner, and cassette tapes passed down across generations.

When my grandmother cooks, she doesn't measure in grams or follow 10-minute timers. She cooks by feel and memory:

"Take a handful of fresh cumin seeds, roast them until fragrant like my mother used to do on Sunday afternoons in Jaipur, then add potatoes until soft..."

Traditional recipe apps fail here because they demand rigid structured inputs. On the flip side, commercial cloud AI services present two severe flaws:

Privacy & Sensitivity: Sending intimate family voice recordings, personal names, and vocal biometrics to third-party cloud LLM APIs surrenders private heritage to remote servers.
AI Hallucinations & Distortion: Standard AI generators tend to "fix" recipes by inventing missing quantities (e.g. inserting 1 tsp salt or 10 mins prep time) when Grandma never specified them, mangling family tradition into generic generic web recipes.

To solve this, I built Grandma's Kitchen—a 100% local, privacy-first, AI-powered family cookbook and memory archive.

What Grandma's Kitchen Does:

Voice-to-Recipe Extraction: Ingests raw audio recordings or live browser voice notes and transcribes them locally via Whisper STT.
Strict Source Grounding & Anti-Hallucination: Extracts ingredients, steps, and timings into structured recipe cards without ever inventing missing details. Unspecified quantities are marked as null with confidence: "unknown".
Memory vs. Cooking Separation: Separates personal anecdotes ("My mother made this every Diwali...") from step-by-step cooking instructions, preserving family memories in a dedicated memory archive tab.
Interactive Provenance Inspector: Every extracted ingredient, step, and story maintains line-by-line provenance linking directly back to original audio transcript quotes.
Local Semantic Search: Allows family members to search by natural questions ("What did Grandma make on cold rainy days?") using local vector embeddings.

Demo

Watch the complete project overview and live walkthrough below:

📺 Video Link: Watch Grandma's Kitchen Demo on YouTube

Key Features Highlighted in the Demo:

🎙️ Live Audio Ingestion: Browser recording with waveform display and instant file upload support for .wav, .mp3, .m4a, and .ogg.
🔍 Source Provenance Modal: Clicking on any ingredient or cooking step opens an evidence drawer showing the exact transcript excerpt and audio context supporting that fact.
📖 Family Memory Archive: View captured stories, relatives mentioned, and cultural occasions tied to each dish.
🖨️ Printable Family Cookbook: Clean, print-ready CSS stylesheet for exporting physical family heirloom cookbooks.

Code

The entire codebase is open-source and available on GitHub:

🐙 GitHub Repository: scha54/Hactoberfest-Weekend-Challenge

grandmas-kitchen/
├── backend/
│   ├── app/
│   │   ├── api/             # FastAPI REST endpoints (recordings, recipes, search)
│   │   ├── core/            # Config, database initialization, security
│   │   ├── db/              # SQLite database session & models
│   │   ├── schemas/         # Pydantic data schemas & JSON specs
│   │   └── services/
│   │       ├── extraction/  # Ollama LLM provider & strict source-grounding prompts
│   │       ├── transcription/# OpenAI Whisper local audio transcription engine
│   │       ├── embeddings/  # Local vector embedding generation
│   │       └── search/      # Local cosine similarity vector search
│   └── tests/               # Pytest suite for API endpoints & extraction logic
├── frontend/
│   ├── src/
│   │   ├── components/      # RecipeSteps, SourceEvidenceModal, AudioRecorder, etc.
│   │   ├── pages/           # UploadPage, CookbookPage, SearchPage, RecipeDetailPage
│   │   └── services/        # API client & audio streaming utilities
│   └── public/              # Static assets & sample recordings
├── data/                    # 100% local persistent storage (audio, SQLite DB, vectors)
└── scripts/                 # Cross-platform 1-click startup scripts (.ps1 & .sh)

How I Built It

Grandma's Kitchen was designed from the ground up around local, open-source AI models and a resilient provider abstraction architecture.

┌─────────────────────────────────────────────────────────────┐
│                       Browser Web UI                        │
│             React + TypeScript + Vite + Tailwind            │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTP / JSON / Audio Stream
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Local Backend                    │
└──────┬───────────────────────┼──────────────────────┬───────┘
       │                       │                      │
       ▼                       ▼                      ▼
┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│ Local STT    │       │ Local LLM    │       │ Embeddings   │
│ Whisper      │       │ Ollama       │       │ Local Vector │
└──────┬───────┘       └──────┬───────┘       └──────┬───────┘
       │                       │                      │
       └───────────────────────┼──────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                        Storage Layer                        │
│         SQLite (Metadata/Data) + Local Disk (Audio)         │
└─────────────────────────────────────────────────────────────┘

1. Local Speech-to-Text (Open-Weight Whisper)

Model: OpenAI Whisper open-weight models running locally via Python (whisper / torch).
Function: Audio files uploaded from the React frontend are written to data/audio/ and transcribed locally without leaving the computer.
Fallback: Includes a native local Python fallback parser to ensure 100% testability even on resource-constrained systems without GPU acceleration.

2. Local LLM Extraction & Anti-Hallucination Framework

Model: Ollama running open-weight LLMs (Llama 3, Mistral, or Qwen) via local HTTP endpoints (http://localhost:11434).
Prompt Engineering & System Constraints: We engineered a strict 7-point System Prompt enforcing strict source grounding:
- Never invent missing quantities: Unmentioned measurements become quantity: null and confidence: "unknown".
- Never assume culinary constants: Vague instructions ("until brown") are kept verbatim rather than converted to guessed minutes.
- Categorize storytelling: Anecdotes and mentions of relatives are placed into stories[], keeping cooking steps clean.
- Require provenance: For every extracted ingredient, step, and story, the LLM must output source_text containing the exact transcript quote.

3. Local Vector Search & Embeddings

Model: Local vector embedding engine calculating semantic dense vector representations.
Search Mechanics: Cosine similarity search over recipe titles, ingredient vectors, and family memory stories, returning ranked results with matching context snippets.

4. Full-Stack Local Technology Stack

Frontend: React 18, TypeScript, Vite, Tailwind CSS, Lucide Icons, and Web Audio API for in-browser audio capture.
Backend: Python 3.10+, FastAPI, Pydantic v2, SQLite (for zero-config relational storage), Pytest.
Deployment: Zero external dependencies. Controlled with 1-line startup scripts (.\scripts\start.ps1 or ./scripts/start.sh).

Why Does Open Innovation Matter?

Open innovation is not just a developer preference for Grandma's Kitchen—it is a fundamental requirement. Here is why open-source AI was irreplaceable for this project:

1. Privacy & Data Sovereignty for Intimate Family Heritage

Voice messages are uniquely personal. They contain non-verbal emotional nuances, family names, home locations, and vocal biometrics. Handing over decades of intimate family voice recordings to proprietary cloud APIs exposes personal heritage to remote server logs, third-party data breaches, and AI training pipelines. Open-weight models (Whisper and Llama) allow families to retain 100% local control over their data.

2. Preserving Qualitative & Cultural Cooking Nuances

Proprietary cloud LLMs are heavily RLHF-tuned toward standard Western commercial outputs. When given informal spoken text, closed models tend to "autocorrect" cultural recipes into standard cookbook formulas—converting a pinch into 1/4 tsp or dropping regional term names. Open models allow custom prompts and open-source fine-tuning that respect qualitative cooking language, family idioms, and regional traditions.

3. Zero Cost & Decade-Long Permanence

Family heirlooms should last for generations. Relying on closed SaaS APIs introduces monthly subscription fees, API pricing changes, and vendor shutdown risks. By building on open-source AI running on local hardware, Grandma's Kitchen costs $0/month to run and will remain functional 10 or 20 years from now, completely independent of cloud service lifecycles.

4. Reproducibility & Community Empowerment

Because every component of this stack relies on open weights and open-source software, any family or developer worldwide can clone our GitHub repository, run a single setup script, and immediately build a private memory vault for their own loved ones.

Open innovation turns technology from a locked walled garden into a living tool for human connection and cultural preservation.

Thank you for reading! Feel free to check out the GitHub Repository and share how you preserve your family's recipes and stories.

Canon Keeper: Reconciling Troublesome Lore

Sandeep Chakravartty — Wed, 30 Sep 2026 07:12:57 +0000

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content

What I Built

CanonKeeper is an AI-powered Fictional Universe Lore & Canon Resolution Engine.

When building expansive fictional universes (fantasy novels, sci-fi series, tabletop RPGs, or gaming franchises), lore accumulated over years frequently suffers from retcons, timeline contradictions, bardic folklore myths, and multi-hop custody chains. Traditional keyword search fails when an early edition book claims a commander entered a citadel in 734, but a later primary garrison ledger signed by the commander proves he remained at a northern outpost until 735.

CanonKeeper solves this by storing structured lore documents in Sanity CMS and running an intelligent Lore Verification Agent that:

Queries atomic claims, source documents, characters, events, and locations via Sanity GROQ & MCP.
Applies Source Authority Hierarchy Weighting (PRIMARY_CANON > OFFICIAL_SECONDARY > REFERENCE > COMMUNITY).
Automatically detects and resolves Timeline Retcons (e.g., 1st Edition Chronicles vs. Imperial Garrison Ledgers & Revised Edition).
Performs Multi-Hop Evidence Deduction to trace artifact possession and event chains across dates.
Renders an Interactive SVG Evidence Graph mapping nodes (Question, Claim, Source, Verdict) and directed relationship edges (retrieves, supported_by, contradicts, supersedes, resolves_to).

Demo

Watch the complete video walkthrough of CanonKeeper in action:

Video Link: https://youtu.be/Qoc_rMhq9z4

Code

Check out the full open-source codebase on GitHub:

🐙 GitHub Repository: https://github.com/scha54/Sanity-MCP-Hackathon

How I Used Sanity

Sanity served as the structured graph foundation for CanonKeeper's knowledge base.

1. Structured Schema Modeling

I designed 5 custom Sanity document schemas:

claim: Represents atomic lore facts with subject-predicate-object triples, source reference, canonStatus (CANON, RETCONNED, DISPUTED, AMBIGUOUS), timeline markers, confidence scores, and reference arrays for contradicts, corroborates, and supersedes.
source: Documents with sourceType (CHRONICLE, MANUSCRIPT, BARDIC_SONG, LEDGER), edition, publicationDate, authorityLevel, and supersedes / supersededBy references.
character: Character entities with aliases, descriptions, first appearance references, and typed relationships.
event: Chronological events with location references, participants, and preceding/following event links.
location: World locations linked to associated characters and events.

2. Sanity Model Context Protocol (MCP) Integration

I configured the Sanity Model Context Protocol (MCP) server integration (https://mcp.sanity.io) in .agents/mcp_config.json. This enables AI agents to inspect schema types and query content via standardized MCP tool calls.

3. GROQ Evidence Queries & Resolution Logic

The agent retrieves evidence from Sanity using GROQ queries:

*[_type == "claim"]{
  _id,
  statement,
  subject,
  predicate,
  object,
  "sourceId": source._ref,
  sourceLocation,
  canonStatus,
  timeline,
  confidence,
  "contradictIds": contradicts[]._ref,
  "corroborateIds": corroborates[]._ref,
  "supersedeIds": supersedes[]._ref,
  notes
}

What the agent does with retrieved Sanity content:

Entity & Intent Recognition: Extracts entities (e.g., Arin Shadowstrider, Valemont Citadel) and timeframe constraints from user queries.
Graph Traversal: Fetches matched claims, resolves linked source document authority levels, and expands contradicts / supersedes graph nodes.
Authority & Retcon Resolution: Overrides outdated claims when a higher authority document (e.g., PRIMARY_CANON revised ledger) supersedes an earlier OFFICIAL_SECONDARY account.
Interactive Visualization: Constructs node-link network graphs displaying claims, sources, and canon verdicts.

Sanity Project Details

Sanity Project ID: demo-universe (Local fallback & Sanity dataset ready)
Dataset: production
Seeding Script: Included at scripts/seed-sanity.ts to populate Sanity CMS datasets using @sanity/client.

Beyond DOM Scraping: Building "THE LAST TERMINAL" with WebMCP

Sandeep Chakravartty — Wed, 02 Sep 2026 18:54:48 +0000

Project Title: THE LAST TERMINAL — WebMCP Escape Room

GitHub Repository: https://github.com/scha54/WebMCP

Live Demo: https://webmcp-blush.vercel.app/

1. Executive Summary & The Problem with Web Agents Today

For the past several years, autonomous browser agents have interacted with web applications primarily through DOM scraping and visual inspection. A typical AI browser workflow involves taking high-resolution screenshots, feeding them into a Vision-Language Model (VLM), predicting pixel coordinates or CSS selectors, and firing synthetic click and keypress events.

This approach suffers from critical flaws:

Fragility: Minor CSS or markup refactors instantly break agent workflows.
Token Inefficiency: Uploading multiple high-res DOM trees and screenshots consumes tens of thousands of LLM tokens per action.
Latency: Visual feedback loops take seconds per step.
Ambiguity: Agents must "guess" button intents without formal input parameter types.

WebMCP (Web Model Context Protocol) is an emerging browser standard that solves this. Instead of forcing AI agents to reverse-engineer visual UIs, WebMCP allows web applications to directly register machine-readable tools (navigator.modelContext.registerTool).

To demonstrate this paradigm shift, we built THE LAST TERMINAL—a polished, browser-based cyberpunk escape room where human players and AI agents collaborate to solve interconnected facility puzzles using shared WebMCP tool capabilities.

2. System Architecture: The Shared Business Logic Principle

The core architectural principle behind THE LAST TERMINAL is Unified Execution Logic. The application never duplicates business logic for human interactions vs. agent interactions.

                 ┌──────────────────────────┐
                 │     WEBMCP AGENT /       │
                 │     DEMO SIMULATOR       │
                 └────────────┬─────────────┘
                              │
                      WebMCP Tool Calls
                              │
                              ▼
 ┌───────────────────────────────────────────────────────────┐
 │                   THE LAST TERMINAL                       │
 │                                                           │
 │  ┌─────────────────────────────────────────────────────┐  │
 │  │                 src/lib/webmcp/                     │  │
 │  │   tools.ts · schemas.ts · registry.ts              │  │
 │  └──────────────────────────┬──────────────────────────┘  │
 │                             │                             │
 │                             ▼                             │
 │  ┌─────────────────────────────────────────────────────┐  │
 │  │                  src/lib/game/                      │  │
 │  │   gameEngine.ts · gameState.ts · puzzles.ts         │  │
 │  └─────────────┬─────────────────────────┬─────────────┘  │
 │                │                         │                │
 │                ▼                         ▼                │
 │  ┌───────────────────────────┐ ┌───────────────────────┐  │
 │  │     Human Visual UI       │ │   Agent Activity      │  │
 │  │  (Facility Map & Systems) │ │   & Tool Trace Log    │  │
 │  └───────────────────────────┘ └───────────────────────┘  │
 └───────────────────────────────────────────────────────────┘

When a human user flips physical switches on the Power Control UI, the component triggers:

restorePower(['C', 'A', 'D', 'B'], 'human');

When an AI agent invokes the WebMCP tool restore_power, the WebMCP execution context routes directly to the identical function:

restorePower(['C', 'A', 'D', 'B'], 'agent');

Both invocations mutate the central GameState, trigger real-time UI updates, emit Web Audio synthesized feedback, and push a structured entry to the Agent Activity Feed.

3. WebMCP Tool Suite (10 Exposed Capabilities)

The application exposes 10 structured tools representing realistic facility subsystems:

#	Tool Name	Description	JSON Input Schema
1	`get_game_state`	Retrieves system lock statuses, discovered clues, and active view	`{}`
2	`inspect_system`	Inspects facility subsystems (`security`, `power`, `archive`, etc.)	`{ "system": "surveillance" }`
3	`read_log`	Reads facility logs by ID (`LOG-2049`)	`{ "logId": "LOG-2049" }`
4	`inspect_surveillance`	Inspects CCTV camera feeds (`CAM-07`) for frame anomalies	`{ "cameraId": "CAM-07" }`
5	`decode_message`	Decodes encrypted ciphers into override candidates	`{ "message": "SURVEILLANCE_ANOMALY" }`
6	`restore_power`	Restores auxiliary power using quad-switch sequence	`{ "sequence": ["C", "A", "D", "B"] }`
7	`unlock_security`	Unlocks security terminal with 4-digit passcode	`{ "code": "7319" }`
8	`open_archive`	Mounts archive database vault (requires auxiliary power)	`{}`
9	`inspect_archive`	Queries archive records matching search terms	`{ "query": "exit protocol" }`
10	`unlock_exit`	Disengages emergency exit pneumatic doors	`{ "code": "7319" }`

JSON Schema & Code Example: `restore_power`

export const RESTORE_POWER_SCHEMA = {
  type: 'object',
  properties: {
    sequence: {
      type: 'array',
      items: { type: 'string' },
      description: 'Ordered list of switch labels, e.g. ["C", "A", "D", "B"].',
    },
  },
  required: ['sequence'],
  additionalProperties: false,
};

// WebMCP Tool Definition
{
  name: 'restore_power',
  description: 'Attempt to restore auxiliary power grid using an ordered 4-switch sequence.',
  inputSchema: RESTORE_POWER_SCHEMA,
  execute: (input: { sequence: string[] }, source = 'agent') => restorePower(input.sequence, source),
}

4. Prerequisite-Driven State Machine

WebMCP tools should not be omnipotent "cheat codes." To demonstrate realistic agent reasoning, tools enforce environment prerequisites:

export function openArchive(source: ToolCallSource = 'agent') {
  // Prerequisite Guard
  if (currentGameState.power === 'offline') {
    const error = {
      code: 'PREREQUISITE_NOT_MET',
      message: 'Facility archive requires auxiliary power. Restore power first.',
    };
    recordToolCall('open_archive', {}, { error }, false, source);
    return { success: false, error };
  }

  currentGameState.archive = 'unlocked';
  // ... state progression
}

If an agent attempts open_archive() while power is offline, WebMCP returns a structured JSON error response code PREREQUISITE_NOT_MET. The agent reads this structured output, inspects logs to discover that power must be restored, and calls restore_power first.

5. WebMCP Tool Registration & Browser Hydration

To register tools safely in React environments without re-registering on component re-renders, THE LAST TERMINAL implements an initialization guard module in src/lib/webmcp/registry.ts:

let initialized = false;

export function registerWebMCPTools(): boolean {
  if (typeof window === 'undefined') return false;
  if (initialized) return isWebMCPAvailableInBrowser;

  try {
    // Polyfill window.__webmcp for browser inspection and agent simulators
    (window as any).__webmcp = {
      tools: WEBMCP_TOOLS,
      callTool: async (name: string, input: any, source = 'agent') => {
        const tool = WEBMCP_TOOLS.find((t) => t.name === name);
        return await tool.execute(input, source);
      },
    };

    // Native WebMCP Imperative API
    const nav = navigator as any;
    if (nav.modelContext && typeof nav.modelContext.registerTool === 'function') {
      WEBMCP_TOOLS.forEach((tool) => {
        nav.modelContext.registerTool({
          name: tool.name,
          description: tool.description,
          inputSchema: tool.inputSchema,
          execute: async (input: any) => await tool.execute(input, 'agent'),
        });
      });
      isWebMCPAvailableInBrowser = true;
    }

    initialized = true;
  } catch (e) {
    console.error('Failed to register WebMCP tools:', e);
  }

  return isWebMCPAvailableInBrowser;
}

6. Live Agent Activity Feed & Execution Trace Inspector

For hackathon judges and developers, transparency is vital. The interface provides two real-time inspection features:

Agent Activity Feed: A live terminal log rendering request/response flow:

   23:51:04  AGENT  → inspect_surveillance("CAM-07")
   23:51:05  SYSTEM ← clue discovered: 7319
   23:51:09  AGENT  → unlock_security("7319")
   23:51:09  SYSTEM ← SECURITY UNLOCKED

Full Agent Trace Modal: A complete JSON log inspector displaying timestamps, source identifiers (human, agent, simulator), JSON inputs, return objects, and execution durations.

7. Zero-Dependency Audio & UI Polish

Web Audio API Synthesizer: Uses standard browser AudioContext to generate retro cyberpunk typing clicks, success chimes, failure buzzers, and power-up sweeps without hosting external MP3 files.
Demo Agent Simulator: Provides a 90-second deterministic agent automated execution mode so judges can experience the full room walkthrough without requiring external AI API keys or specialized browser extensions.

8. Setup, Testing & Deployment

Repository Setup

git clone https://github.com/scha54/WebMCP.git
cd WebMCP
npm install

Running Tests

# Run isolated Game Engine test suite
npm run test:engine

Production Build & Vercel

# Next.js static build check
npm run build

# Deploy to Vercel
vercel --prod

9. Conclusion: The Future of Agentic Web Interfaces

WebMCP transforms web applications from passive visual UIs into agentic APIs. By exposing structured tools alongside standard visual components, websites become directly operable by AI models with 90%+ token reduction and near-zero latency.

THE LAST TERMINAL proves that building WebMCP-compatible web apps is clean, robust, and framework-agnostic.

Check out the source code on GitHub.
Explore the live demo and test the WebMCP tools yourself!

LifeOps: Delegating Outcomes, Not Checklists

Sandeep Chakravartty — Mon, 31 Aug 2026 18:56:55 +0000

Repository: https://github.com/scha54/All-Things-Agentic-Hackathon

Technology Stack: Google ADK, Gemini API, Python, FastAPI, SQLite, React, TypeScript, Vite

Abstract

Most personal AI tools today operate as passive text synthesizers. When faced with a complex life event—such as relocating to a new apartment—users are forced to manage an exhausting checklist: reading contract terms, notifying utility vendors, scheduling installation technicians, reserving movers, updating addresses, and tracking deadlines.

LifeOps introduces a paradigm shift in personal software engineering: Outcome Delegation. Instead of prompting an assistant for step-by-step instructions, the user delegates a high-level outcome: "Sort out my broadband and apartment move situation." LifeOps autonomously investigates available documents, constructs a task dependency graph, executes low-risk background actions, pauses deterministically for human approval on high-risk operations, monitors progress asynchronously, and verifies completion against provider APIs.

This article details the design, agent hierarchy, risk guardrails, verification loops, and zero-cloud local deployment architecture of LifeOps.

1. The Architectural Shift: Chatbot vs. Autonomous Operations Agent

Traditional AI interactions follow a synchronous request-response loop:

CHATBOT PARADIGM:
User  ───►  Question ("How do I cancel my internet?")  ───►  LLM  ───►  Advice Text

LifeOps transforms this into an event-driven operational workflow:

LIFEOPS AUTONOMOUS PARADIGM:
User
 │
 ▼
Delegate Outcome ("Move my internet and apartment services")
 │
 ├──► Discovery Agent (Inspects lease & bill PDFs, extracts dates & policy constraints)
 ├──► Planning Agent (Constructs 7-step task dependency graph)
 ├──► Execution Agent (Submits utility notices, queries technician slots)
 ├──► Risk Engine (Pauses HIGH-risk booking for Human Approval)
 ├──► Verification Agent (Queries provider DB to confirm booking)
 ├──► Event Monitor (Detects vendor cancellation ──► Autonomously Replans ──► Rebooks)
 │
 ▼
✓ LIFE OPERATION RESOLVED

2. Multi-Agent Orchestration with Google ADK

LifeOps is engineered around the Google ADK (Agent Development Kit v2.3.0) framework. Rather than inflating agent counts for cosmetic appeal, every agent fulfills a distinct operational role:

flowchart TD
    User([User Outcome Input]) --> API[FastAPI Server]
    API --> Orchestrator[Orchestrator Agent]

    Orchestrator --> DB[(Local SQLite DB)]
    Orchestrator --> Discovery[Discovery Agent]
    Orchestrator --> Planner[Planning Agent]
    Orchestrator --> Execution[Execution Agent]

    Execution --> DocAgent[Document Agent]
    Execution --> ResearchAgent[Research Agent]
    Execution --> CommAgent[Communication Agent]

    Execution --> Verification[Verification Agent]

    Verification --> DB
    Orchestrator --> RiskEngine[Deterministic Risk Engine]
    RiskEngine --> ApprovalRequest{Human Sign-Off Needed?}
    ApprovalRequest -- Yes --> Pause[Pause & Queue Approval]
    Pause --> UI[Command Center UI]
    UI -- Approve --> Resume[Resume & Verify]

Specialist Agent Responsibilities:

Orchestrator Agent: Maintains overall workflow state, step transitions, risk evaluations, and paused state recovery.
Discovery Agent: Inspects local document vaults (current_lease.txt, new_lease.txt, internet_bill.txt, utility_bill.txt) and extracts structured facts with confidence ratings.
Planning Agent: Builds task graphs with explicit parent-child dependency bindings.
Execution Agent: Interacts with mock digital provider APIs.
Document Agent: Extracts lease dates, notice windows, and contract penalties.
Research Agent: Scans provider slots and compares pricing options.
Communication Agent: Drafts formal move-out notices and vendor emails (enforcing strict separation between DRAFT and SEND).
Verification Agent: Queries mock system databases to confirm outcome states rather than blindly trusting tool output.

3. Deterministic Safety: The Human-in-the-Loop Risk Engine

A major failure mode in modern agentic systems is allowing LLMs to execute irreversible financial or legal actions without boundary controls. LifeOps solves this by enforcing a deterministic, application-level Risk Engine:

Action Name	Risk Level	Action Taken
`read_document`, `extract_facts`	LOW	Auto-Executed
`query_provider_api`, `check_slots`	LOW	Auto-Executed
`draft_email`, `send_notification`	MEDIUM	Auto-Executed
`request_internet_transfer`	MEDIUM	Auto-Executed
`book_moving_company` (Cost: ₹12,500)	HIGH	PAUSES WORKFLOW — Requires Approval
`book_broadband_installation`	HIGH	PAUSES WORKFLOW — Requires Approval
`financial_transaction`, `cancel_contract`	CRITICAL	PAUSES WORKFLOW — Requires Approval

When an action triggers HIGH or CRITICAL risk (or involves financial expenditure), LifeOps pauses the workflow, emits an APPROVAL_REQUESTED event, and presents a structured card to the user containing:

What: The proposed action
Cost: The financial commitment
Why: Operational rationale
Evidence: Document sources & quotes
Controls: [Approve & Resume] or [Reject]

4. Asynchronous Resilience & Self-Healing Event Replanning

LifeOps state is stored in a local SQLite database (lifeops.db) configured with Write-Ahead Logging (WAL) for concurrency. If the application or machine restarts mid-operation, LifeOps inspects unfulfilled workflows and resumes idempotent tasks without duplicating actions.

The "Wow Moment": Vendor Cancellation Recovery

During the primary demo scenario, a simulated external emergency occurs: SwiftShift Movers cancels the moving booking due to vehicle breakdown.

LifeOps reacts autonomously:

Event Reception: Listens to mock system webhooks (EXTERNAL_EVENT_RECEIVED).
State Transition: Marks the original movers task as CANCELLED.
Autonomous Replanning: Wakes up, triggers the Research Agent to query replacement options (Metro Express Logistics at ₹11,500), and generates a new approval request.
Sign-Off & Verification: Once approved, books the replacement and verifies the confirmation code in the provider database.

5. Local-First, No-GCP Compliance Architecture

To ensure strict privacy and developer accessibility, LifeOps operates 100% locally:

Zero Cloud Infrastructure: 0 dependencies on Cloud Run, Firestore, Pub/Sub, Vertex AI, or Secret Manager.
Direct Model Inference: Connects directly to the Gemini API (gemini-3.5-flash / gemini-2.5-flash) via GEMINI_API_KEY stored in .env.
Local Audit Tool: Includes scripts/check_no_gcp.py to audit the repository for prohibited cloud imports or hardcoded keys.

LifeOps Infrastructure Audit
=============================================
Google ADK:       PASS
Gemini API:       PASS (Managed via local .env)
GCP Services:     NONE DETECTED
Secret Leaks:     CLEAN (0 hardcoded keys in source)
SQLite:           PASS
Local Scheduler:  PASS
=============================================
Result: PASSED (NO-GCP & CLEAN SECRETS)

6. Repository & Setup Instructions

The full working source code is available on GitHub:

📌 GitHub Repository: https://github.com/scha54/All-Things-Agentic-Hackathon

Running Locally:

Clone & Configure Environment:

   git clone https://github.com/scha54/All-Things-Agentic-Hackathon.git
   cd All-Things-Agentic-Hackathon
   cp .env.example .env
   # Add your GEMINI_API_KEY to .env

Initialize Database:

   python scripts/init_db.py

Start Mock Digital World (Port 8001):

   python mock_world/server.py

Start FastAPI Backend (Port 8000):

   python -m uvicorn backend.app.main:app --reload --port 8000

Start React Dashboard:

   cd frontend
   npm install
   npm run dev

Run Audits & Tests:

   python scripts/check_no_gcp.py
   python -m unittest discover backend/tests

7. Conclusion

LifeOps proves that personal AI can transcend conversational chat boxes to become true autonomous operations centers. By pairing Google ADK multi-agent orchestration and Gemini document intelligence with deterministic risk guardrails and local SQLite persistence, LifeOps delivers a secure, privacy-preserving solution where users delegate outcomes and software handles the operational heavy lifting.

Cooking with CSS: Coding 'One More Bite' — The Steaming Comfort Food Oracle

Sandeep Chakravartty — Sun, 16 Aug 2026 19:56:23 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, CSS Art._

Inspiration
When thinking about comfort food, we didn't want to design another generic, calorie-counting recipe database. We wanted to capture the emotional warmth of food—the quiet feeling of sitting in a sun-drenched digital kitchen at golden hour.

Our CSS and SVG art was inspired by:

The Steaming Golden-Hour Soup Bowl: A centerpiece illustration on the landing page representing immediate warmth. It features hand-crafted SVG elements, custom CSS floating spice particles (drifting at varying speeds), and rising steam lines.
The Dynamic Hunger Bowl: An interactive piece of SVG art tied to our custom hunger slider. As you slide from "Just peckish" to "Feed me immediately", the bowl physically expands, fills up with colorful broth (shifting from soft peach to deep tomato red), and populates with ingredients like tofu blocks, sliced carrots, green scallions, and hot steam.
The visual theme uses an editorial cream-paper texture, soft espresso typography, and organic card borders to feel like a handwritten note from a close friend.

Demo
Here is a preview of the interactive comfort food experience:

One More Bite Interactive Demo

GitHub Repository: scha54/One-More-Bite
Journey

Setting up Tailwind CSS v4 and Vite We initialized a clean React + TypeScript project and integrated the new Tailwind CSS v4 plugin. Tailwind v4's CSS-first theme configuration allowed us to set up our warm, cozy palette variables directly in src/index.css using standard theme directives:

css

@theme {
--font-serif: "Fraunces", Georgia, serif;
--font-sans: "Manrope", sans-serif;
--color-cream: #FAF5EC;
--color-paper: #FFFDF9;
--color-espresso: #2D221C;
--color-terracotta: #C85A3C;
--color-saffron: #EAA93E;
--color-olive: #6E7753;
--color-peach: #EBB99D;
}
We layered an inline base64 SVG fractal noise pattern on the body tag to establish a warm, tactile paper parchment background texture without incurring external asset load costs.

Building the Interactive CSS/SVG Art The highlights of the implementation are the micro-interactions:

The Hunger Slider: We built a custom slider track. We intercepted the range input onChange event in React, updating a scale factor and content rendering arrays. The SVG tofu, carrot, and scallion vectors are conditionally rendered based on hunger levels 1 through 4.
The Reveal pay-off Loader: The transition from the quiz to the result spins a golden plate SVG using a slow linear animation keyframe, while rapidly cycling comfort food names inside. This creates a playful, rewarding anticipation loop before displaying your match.

Personalization & The Addictive Recommendation Loop
We coded a local, client-side recommendation engine that weighs candidate scores using your cuisine, emotional state, and hunger level. To build a delightful repeat loop, we implemented a "One More Bite" button. This passes an array of previously matched IDs to our engine, executing an exclusions filter so that clicking it rolls a new compatible recommendation (e.g. transitioning from Masala Dosa to Moong Dal Khichdi or Rajma Chawal on the same selections) with a fresh transition animation.
Accessibility as a Core Feature
Rather than treating accessibility as an afterthought, we ensured:

The progress indicator lists screen-reader hidden text descriptions (Question 2 of 3).
Visible focus ring offsets outline all select buttons and sliders when tabbing.
A media query listener immediately overrides and halts all rotating plates, floating spice particles, and rising steam lines if a user prefers reduced motion:
css

@media (prefers-reduced-motion: reduce) {
.animate-steam, .animate-float-slow, .animate-spin-slow {
animation: none !important;
transform: none !important;
}
}
This project reminded us that focusing on polish, smooth transitions, and visual storytelling is often far more rewarding than adding complex databases and unnecessary backends. Sometimes, a beautiful static frontend is exactly what you need.

Made with 🧡 for DEV Community.

PawPrint: Unleashing AI-Powered RPG Dog Cards with Gemini 2.5 Flash 🐾

Sandeep Chakravartty — Sun, 16 Aug 2026 14:46:53 +0000

This is a submission for Weekend Challenge: Dog Days Edition

What I Built
PawPrint is a web application that lets dog owners transform their real-life furry companions into fully playable, custom RPG character cards!

By uploading a photo of their pup and taking a quick personality quiz (covering habits like where they sleep, how they react to the doorbell, or their behavior on walks), users can forge high-fidelity RPG cards. The app generates:

RPG Class: Including archetypes like Bark Mage, Treat Paladin, Nap Rogue, and Chaos Ranger.
Rarity: Grading from Common, Uncommon, Rare, Epic, up to Legendary.
Stats: HP, Attack, Defense, and Speed based on the quiz questions and card rarity.
Unique Abilities: Fun, class-specific active, passive, and ultimate abilities with comedic lore descriptions.
Weaknesses & Backstories: Tailored backstory bios explaining their origin and a hilarious weakness (like "The Dreaded Vacuum Cleaner" or "Baths").
Beyond card generation, the app features:

Persistent Deck Roster: Keep track of all generated dogs, stored offline in the browser's localStorage.
Deck Management: Full search and sorting controls (by name, breed, date, and stats), and filters by RPG Class or Rarity.
Interactive Battle Arena: A turn-based combat simulator where you can duel two dogs, or test your dog's mettle against built-in legendary AI bosses like Sir Mailman (Letter Knight) or The Dreaded Vacuum (Chaos Devourer).
Instant Card Sharing: Share individual dogs using encoded query-string URLs (?card=...) that allow other users to view and import the card with a single click.
Theme Support: Seamless toggle between sleek dark and clean light modes.
Demo
You can try the live app here: PawPrint Live Site (Replace this with your actual deployed URL!)

(To see it in action without configuring an API key, the app runs in local Demo Mode with a deterministic rule-based generator!)

Code
The project is fully open-source and hosted on GitHub:

scha54 / Pawprint

Vibe coded this application with Antigravity and Gemini for the Dev.to Weekend Challenge

🐾 PawPrint RPG Card Generator

PawPrint is an AI-powered tabletop RPG character card generator for dog owners. By uploading a photo of their dog and answering a short personality quiz, users can forge a high-fidelity RPG card complete with customized stats, unique abilities, comedic weaknesses, and a custom lore backstory.

The project features a client-side implementation of the Google Gemini API, a persistent roster of saved cards, and an interactive Battle Arena where dogs can face off against each other or challenge legendary AI opponents.

✨ Features

🧙‍♂️ Personality Quiz: 5 interactive questions to gauge your dog's temperament (sleeping style, doorbell response, walks behavior, etc.) which influence their statistics and RPG class.
🎨 AI-Powered Card Forging: Analyzes the dog's picture and personality questions using Gemini 2.5 Flash (or a fallback offline simulator) to generate names, breeds, class, rarity, abilities, and origin stories.
💾 Persistent Deck Roster: Cards…

View on GitHub

(Or visit the repository directly at github.com/scha54/Pawprint)

How I Built It
🛠️ The Tech Stack
Framework: React 19 + TypeScript + Vite (for lightning-fast HMR and type-safety)
Styling: Tailwind CSS v4 + Vanilla CSS Custom Tokens (enabling easy light/dark mode configuration)
AI Core: Google Generative AI SDK (@google/generative-ai)
Icons: Lucide React
Exporting: html-to-image (allowing users to download their cards as PNG images)
Testing: Vitest (for core game logic and storage helper tests)
🧠 Google Gemini Integration
PawPrint relies on the Google Generative AI SDK, querying the Gemini 2.5 Flash model directly from the client. When a user submits their pup's photo and quiz answers, we build a multimodal prompt:

Multimodal Inputs: We pass the compressed image base64 data and the options chosen during the quiz.
Structured JSON Output: To make the generation reliable, we utilize the SDK's responseMimeType: 'application/json' configuration, forcing Gemini to respond with a JSON payload that perfectly fits our TypeScript DogCharacter interface. This eliminates the need for messy string parsing or regex matching.
Local Mock Fallback: In the absence of an API key, we wrote an offline character engine (src/services/gemini.ts) that uses the quiz options' mathematical modifiers to calculate stats, choose classes, and assign preset abilities—providing a seamless demo mode experience.
💾 Canvas Image Compression
Because we want cards to persist in browser storage, we had to solve a major limitation: localStorage is capped at roughly 5MB. Standard mobile phone photos are often 3MB–10MB, which would immediately crash the storage. To solve this, the ImageUploader component loads uploaded images into an HTML5 element, downscales them to a maximum boundary of 500px (preserving aspect ratio), and encodes them as a JPEG with a quality factor of 0.85. This compresses the base64 string to just 20–50KB, allowing users to save dozens of cards effortlessly.

⚔️ turn-Based Battle Engine
The Battle Arena simulator uses a custom deterministic scoring system (src/utils/scoring.ts):

Turn Order: The dog with the highest Speed stat acts first.
Elemental Advantages: We coded a rock-paper-scissors class advantage system: Bark Mage beats Treat Paladin -> Treat Paladin beats Nap Rogue -> Nap Rogue beats Chaos Ranger -> Chaos Ranger beats Bark Mage. A class advantage boosts final damage by 25%.
Combat Logic: Turn damage is calculated as (Attack / (Defense * 0.8)) * 15 * advantage. Round 1 triggers passive abilities, subsequent rounds utilize basic pounces, and dropping below 40% health triggers massive ultimate moves!
Prize Categories
This project is submitted for:

Best Use of Google AI: Featuring a clean client-side implementation of the Gemini 2.5 Flash model with the official @google/generative-ai SDK. It demonstrates the strength of multimodal prompts (image + text) combined with structured JSON outputs, showing how developers can leverage Gemini to build immersive, interactive gamified experiences in a lightweight serverless frontend.

Build a Production-Grade AI Dashboard: Architectural Insights from the BMW AutoTrend Platform

Sandeep Chakravartty — Sat, 01 Aug 2026 11:06:02 +0000

Orchestrating Clean Architecture, Subprocess Scrapers, SQLite FTS5, and Local LLMs (Ollama) inside a Dockerized Python + React Stack.

1. Executive Summary & Design Goals

The BMW AutoTrend Dashboard is a local-first, AI-powered automotive intelligence platform that scrapes, processes, classifies, and visualizes market trends and sentiment for BMW-related news. The system is designed to run completely locally, using a local LLM instance via Ollama for article summarization and entity extraction, backed up by a deterministic rule-based regex fallback engine.

The platform was built with the following design goals:

Clean Architecture: Decouple the data extraction layer, storage mechanism, analytical computations, and API controllers.
Deterministic Fallbacks: Ensure the application remains fully functional (using a rule-based regex processor) even when local LLM resources (Ollama) are offline or resource-constrained.
Local-First & High Performance: Use SQLite FTS5 for instant full-text search, keeping all scraped data, search indexes, and analysis files stored locally without external SaaS API dependencies.
Plug-and-Play Extensibility: Allow plugging in new scraping adapters (e.g., Autoblog, MotorTrend) by implementing a unified abstract interface.

2. Clean System Architecture

The application adheres to Clean Architecture principles, maintaining a strict unidirectional data flow and isolating business logic from external dependencies.

graph TD
    subgraph Frontend [React SPA - Served via Nginx]
        UI[Interactive Dashboard Pages]
        RC[Recharts Visualizations]
        FTS_UI[Spotlight Search UI]
    end

    subgraph Backend [FastAPI Application]
        API[FastAPI Endpoints]
        SCH[APScheduler Ingestion & Snapshots]
        ING[Ingestion Pipeline]
        ANA[Analytics Engine]
        AIP[AI Processing Pipeline]
    end

    subgraph CLI Bridge [Subprocess Execution]
        WBC[Webcmd CLI + BMWBLOG Plugin]
    end

    subgraph Storage [Local Storage]
        DB[(SQLite Database)]
        FTS[(FTS5 Search Index)]
    end

    subgraph Local LLM [AI Inference]
        OLL[Ollama Server]
    end

    UI -->|Queries| API
    API -->|Reads/Writes| DB
    ING -->|Executes| WBC
    WBC -->|Scrapes Web Data| BMWBLOG[BMWBLOG Site]
    ING -->|Sends content for classification| AIP
    AIP -->|Requests JSON| OLL
    AIP -->|Regex Fallback| AIP
    SCH -->|Triggers| ING
    SCH -->|Runs daily| ANA
    ANA -->|Computes stats| DB
    FTS_UI -->|Queries FTS| API
    API -->|FTS Match Query| FTS

Frontend Layer: A React + TypeScript SPA built with Vite. It interacts with the backend strictly via standardized JSON REST endpoints.
API Controllers: FastAPI handlers that validate schemas using Pydantic, query storage, and trigger background tasks.
Core Business Logic:
- The Ingestion Pipeline orchestrates scraping, duplicate checks, and data ingestion.
- The AI Processing Pipeline performs text analysis, summarization, and tag extraction.
- The Analytics Engine aggregates metrics and maintains daily snapshots.
Data Providers: Subprocess wrappers encapsulating the execution of Node.js-based CLI tools (webcmd).
Database Layer: SQLite managed via SQLAlchemy ORM, enriched with raw SQL database triggers.

3. Ingestion Pipeline & Subprocess WebCMD Scraping

Data ingestion begins with the abstract base class NewsProvider in [providers/base.py]. Concrete providers, such as the BMWBlogProvider in providers/bmwblog.py, are responsible for crawling data from publishers.

Rather than writing custom web scrapers that are brittle and hard to maintain, the backend utilizes the @agentrhq/webcmd CLI tool under the hood. The BMWBlogProvider executes webcmd as a subprocess to retrieve structured article feeds.

The Subprocess Execution Mechanism

# snippet from backend/providers/bmwblog.py
def _run_webcmd(self, args: List[str]) -> str:
    cmd = ["webcmd"] + args
    try:
        # We use shell=True on Windows because webcmd is a script (.ps1 or .cmd)
        is_windows = os.name == 'nt'
        result = subprocess.run(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            shell=is_windows,
            check=True
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        logger.error(f"webcmd execution failed: {result.stderr}")
        raise Exception(f"webcmd error: {result.stderr}")

The pipeline executes in two stages:

Metadata Fetching: Runs webcmd bmwblog latest -f json to retrieve the latest 10 articles (metadata only: URLs, titles, brief excerpts).
Deep Article Ingestion: For each new URL (determined by checking the SQLite index), it queries webcmd bmwblog article <url> -f json to extract the full body text, category, author, and scrapes the raw HTML for OpenGraph images (og:image).

4. Hybrid AI Classification Pipeline (Ollama & Regex Fallbacks)

Once full article text is ingested, it is dispatched to ai/processor.py. The processor uses a hybrid system that dynamically checks Ollama's availability before selecting an evaluation engine:

graph TD
    A[New Article Ingested] --> B{Is Ollama Server Online?}
    B -->|Yes| C[Call Ollama Llama 3.2 API]
    C --> D{Parsing JSON Successful?}
    D -->|Yes| E[Save AI Classification to Database]
    D -->|No| F[Fallback to Regex Rule Engine]
    B -->|No| F
    F --> G[Extract Entities, Sentiment, & Summaries via Rules]
    G --> E

1. Ollama LLM Pipeline

If the Ollama server is online and running llama3.2, the backend posts to /api/generate with a carefully crafted prompt. To ensure deterministic integration, the request forces a structured JSON output:

payload = {
    "model": settings.OLLAMA_MODEL,
    "prompt": prompt,
    "format": "json",
    "stream": False,
    "options": { "temperature": 0.1 }
}

The model classifies sentiment (Positive, Neutral, Negative), extracts relevant vehicle models (e.g., Neue Klasse, BMW M3), maps technology tags (e.g., Battery Technology, ADAS), and generates short, detailed, and TL;DR summaries.

2. Rule-Based Regex Fallback Pipeline

If Ollama is offline (or fails to return valid JSON), _analyze_with_rules executes. It uses pre-compiled regular expressions to match keywords and tags:

TECHNOLOGY_TAGS = {
    "Electric Vehicles": r"\b(ev|evs|electric|zero-emission|zero emission|battery electric|bev)\b",
    "Battery Technology": r"\b(battery|batteries|solid-state|cell|cells|rimac)\b",
    "Autonomous Driving": r"\b(autonomous|self-driving|driverless|autopilot)\b",
    # ...
}

# Sentiment heuristic based on term tallying
pos_count = sum(len(re.findall(rf"\b{word}\b", combined_text)) for word in SENTIMENT_POSITIVE)
neg_count = sum(len(re.findall(rf"\b{word}\b", combined_text)) for word in SENTIMENT_NEGATIVE)

This hybrid model guarantees that database columns are populated with valid categories and tags, and that search capabilities are never compromised by hardware limitations.

5. High-Performance SQLite FTS5 Search Indexing with Database Triggers

For high-speed, local-first search, the project bypasses slow LIKE %query% SQL operations and utilizes SQLite's native FTS5 (Full-Text Search) extension.

Database Schema Initialization and Triggers

In database/connection.py, the application boots the database using SQLAlchemy, but hooks into standard connection events to enforce foreign key constraints (PRAGMA foreign_keys=ON) and manually provisions an FTS5 virtual table + synchronization triggers:

-- FTS5 Virtual Table Configuration
CREATE VIRTUAL TABLE articles_fts USING fts5(
    title, 
    excerpt, 
    content, 
    content='articles'
);

-- Synchronization Triggers (Insert, Delete, Update)
CREATE TRIGGER articles_ai AFTER INSERT ON articles BEGIN
    INSERT INTO articles_fts(rowid, title, excerpt, content)
    VALUES (new.id, new.title, new.excerpt, new.content);
END;

These triggers offload search indexing directly to the SQLite engine. Whenever a new article is committed via SQLAlchemy, SQLite automatically indexes the title, excerpt, and content inside the FTS5 shadow tables.

Relevance-Based Search Endpoint

When a user searches the dashboard, the backend performs a BM25 relevance-ranking query:

# Snippet from backend/api/routes.py
query_str = """
    SELECT rowid FROM articles_fts 
    WHERE articles_fts MATCH :query
    ORDER BY bm25(articles_fts)
"""
result = db.execute(text(query_str), {"query": search_term})

This executes in sub-milliseconds, giving the frontend instantaneous "Search-as-you-type" capabilities.

6. Dynamic Analytics Engine & Rolling Trend Computations

The Analytics Engine in analytics/engine.py performs rolling window calculations to determine which automotive trends are gaining traction.

Instead of tracking basic counts, the engine computes a weekly growth rate by comparing mentions of vehicle models and technologies over a rolling 7-day window vs the preceding 7-day window.

# 7-day boundaries
seven_days_ago = today_start - timedelta(days=7)
fourteen_days_ago = today_start - timedelta(days=14)

# Mentions in last 7 days (recent) vs 7-14 days ago (previous)
# Growth calculation:
if prev_cnt == 0:
    growth_pct = 100.0 if recent_cnt > 0 else 0.0
else:
    growth_pct = ((recent_cnt - prev_cnt) / prev_cnt) * 100.0

The resulting topics are sorted by growth_rate DESC to populate the "Trending Topics" widgets in the UI.

Historical Snapshotting

To prevent CPU-heavy aggregations every time a user loads the page, the application uses APScheduler to execute generate_daily_snapshot near midnight. This function serializes the calculated statistics to JSON and stores it in the analytics_snapshots table, enabling fast rendering of historical timelines over 30 days.

7. Frontend Architecture (React + Vite + Recharts)

The frontend is a single-page application built on a modern React + TypeScript + Vite architecture.

UI Features

Glassmorphic Theme: A premium dark-mode interface built on CSS variables, custom Outfit typography, and glowing borders.
Component Layout: The sidebar and main panels are structured in layouts/DashboardLayout.tsx for responsive navigation.
Visualizations: Uses Recharts to display dynamic data:
- Area charts for daily article volumes.
- Sentiment timelines mapping Positive/Neutral/Negative trends over a 30-day period.
- Bar charts comparing vehicle model and technology tag popularity.
Real-time Search: Ingests keypresses, queries the SQLite FTS5 index via the API, and highlights matches with sub-millisecond lag.

8. Docker Orchestration & DevSecOps Insights

The platform is designed to launch with a single command: docker compose up --build. The orchestration configures three networks-isolated, dependent containers:

Ollama Container: Pulls and serves LLM models on port 11434.
FastAPI Backend Container: Built from docker/backend.Dockerfile. It maps the database to a persistent Docker volume db_data at /app/data/autotrend.db so database records are saved permanently across container restarts.
Nginx Frontend Container: A multi-stage build that compiles the React application and uses Nginx to serve the static assets on port 80, proxying requests to the backend.

Technical Docker Tip: Node.js Subprocess Requirement

Since the python backend invokes webcmd (an npm library) as a subprocess, the backend Dockerfile must be configured to support a multi-runtime environment. Adding Node.js, npm, and installing @agentrhq/webcmd globally inside the python slim container ensures the ingestion pipeline compiles without error:

FROM python:3.12-slim
WORKDIR /app

# Install Node.js, NPM, and global webcmd CLI scraper
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential curl gnupg \
    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs \
    && npm install -g @agentrhq/webcmd \
    && webcmd plugin install github:agentrhq/webcmd/bmwblog \
    && rm -rf /var/lib/apt/lists/*

9. Extensibility & Future Scope

The design of the AutoTrend Dashboard makes it easily expandable:

Adding New News Outlets: Create a new class implementing the NewsProvider abstract base class (e.g. AutoblogProvider). Map the scraper plugin commands (e.g. webcmd autoblog latest), and register the provider in run_ingestion_pipeline.
External LLMs: The AI client in [ai/client.py] can be extended to support remote cloud models (such as the Gemini API or OpenAI API) using environment variables for API keys.
Advanced Sentiment Heuristics: The rule-based engine can be upgraded to support VADER or transformer models (like Hugging Face's distilbert-base-uncased-finetuned-sst-2-english) for deep offline sentiment extraction.

Created as technical documentation for the BMW AutoTrend Dashboard codebase.Github Repo at https://github.com/scha54/BMW-AutoTrend-Dashboard