Decision Trace

Decision Trace is a decision intelligence layer powered by Google Gemini.

Comment

Inspiration

Decision making in organizations is often messy: notes in emails, slack threads, teams, outlook and documents with no clear audit trail. When AI is involved, its hard to see what it influenced and what humans overrode. I built Decision Trace to turn that chaos into structured, auditable records - so teams can show how decisions were made, what evidence supported them, and who was accountable.

I was inspired by a simple but critical gap: teams can easily state what they decided, but struggle to explain why, especially weeks or months later. This lack of traceability creates risk, weakens accountability, and makes it hard to learn from past decisions.

What it does

Decision Trace turns unstructured decision content into Decision Ledgers - audit ready reports that capture:

  1. Decision - Outcome, confidence, trace score (0-100), rationale.
  2. Flow - Steps with actor (AI/Human/System), AI Influence, overrides, rules.
  3. Evidence - What was used, weight, and impact on confidence.
  4. Risks - Identified, accepted, severity, mitigation
  5. Assumptions - Explicit, Validated, Owner, Invalidation Impact.
  6. Accountability - RACI (Responsible, Accountable, Consulted, Informed).

You upload PDF/DOCX/TXT, click Run Gemini 3 Analysis, and get a 6 tab report. Demo mode works without an API key so anyone can try it.

How I built it

  1. Frontend: Next.js 14 (App router), React 18, Tailwind CSS
  2. AI: Google Gemini 3 with structured JSON output and schema enforcement.
  3. Backend: Next.js API routes, Prisma (PostgreSQL/SQLite), Supabase for report storage.
  4. Flow: Upload the document -> Run Gemini 3 Analysis -> Report
  5. Gemini: Single call Decision Ledger generation with responseMimeType: application/json and system instructions for audit semantics
  6. Testing: Vitest (unit/integration), Playwright (E2E), GitHub Actions CI

Challenges I ran into

  1. Structured Output: Getting Gemini to return valid JSON for a complex schema. I fixed this with responseMimeType: application/json, a JSON schema, and strict system instructions.
  2. Demo Mode: Making the app usable without an API key. I added mock responses and a deterministic demo case so judges can try it immediately.
  3. E2E Stability: Flaky tests around navigation and readiness. I added clear status markers (qs-upload-ok) and deterministic readiness checks.

Accomplishments that I am proud of

  1. Schema enforced AI output: Decision Ledger is validated against a JSON schema before use.
  2. Audit semantics: Actor (AI/Human/System), AI influence, and overrides are tracked per step.
  3. Zero cost demo: Works fully without an API key on free tiers (Vercel, Neon, Supbase, Gemini).
  4. Test Coverage: Unit, Integration, and E2E tests with mocked Gemini and CI.

What I learned

  1. Structured Output: Using responseMimeType and JSON schema with Gemini makes responses reliable and parseable.
  2. System Instructions: Clear, specific instructions (ex: actor enums, required fields) improve consistency.
  3. Demo first design: Designing for demo mode first makes the app easier to try and judge.
  4. Deterministic E2E: Readiness and status markers reduce flakiness in automated tests.

What's next for Decision Trace

  1. Real-time collaboration: Multiple users editing and annotating the same decision ledger.
  2. Export formats: PDF and word reports for compliance and sharing.
  3. Integrations: Slack, Microsoft teams, and document storage (ex: one drive, google drive) for input and output.
  4. Historical Comparison: Compare decisions over time and track how similar cases were handled.
  5. Custom Schemas: Let organizations define their own Decision Ledger fields and workflows.
  6. Enterprise Style UI: Report layout and styling suitable for compliance and governance.

Built With

Share this project:

Updates