Delividence

• 

  Landing Page — Hero section introducing the core value prop "The brief is more than the brief." with CTAs to create a record or see a sample

• 

  Sign-In Page — Google OAuth login screen with "Continue the record" heading

• 

  Workspace dashboard — Work queue, current run status, and brief input to create a project record

• 

  Freelancer actions — Generate client links, attach evidence, and view the acceptance record

• 

  Client confirmation portal — No-account page where the client confirms the baseline

• 

  Scope change detection — AI classifies a new client request against the baseline, flags a change

• 

  Delivery review — Criteria listed with PENDING, CHANGES_REQUESTED, and ACCEPTED statuses

• 

  Sources page — All ingested briefs and notes with extraction status and item counts

• 

  Review page — Aggregated view of records with criteria counts and review status

• 

  Activity page — Chronological event log with timestamps and status badges

• 

  Working policies — Freelancer defaults (e.g. revision rounds) that never override client words

• 

  Records page — Master list of all project records with baseline version and status

• 

  Cloud Run services — Production infra showing delividence-api and delividence-worker deployed

• 

  Cloud Run metrics — Live request count, latency breakdown, and uptime for the API service

• 

  Closing shot — "Delividence removes manual chasing while keeping a human in control."

Inspiration

Freelance projects often drift because a vague brief becomes an untracked assumption. New requests overwrite the original agreement, and delivery evidence becomes disconnected from what the client actually approved. Delividence turns that friction into a clear, shared decision trail.

What it does

Delividence is a two-party AI scope and acceptance protocol for freelancers and clients. It extracts a source-linked project ledger from a typed brief, creates a no-account client confirmation flow, freezes a versioned baseline only after client confirmation, and classifies later requests against that baseline with a citation. Delivery evidence is attached to exact acceptance criteria, then the client can accept or request changes per criterion in a single review.

The owner workspace includes Workspace, Records, Sources, Review, Activity, and Policies. The demo walks through each: create and extract a record, inspect provenance, confirm a baseline, classify a scope change, attach evidence, submit client review, inspect the audit trail, and show the configurable policy surface.

How we built it

• Next.js frontend, deployed on Vercel; Firebase Authentication protects owner routes and scoped opaque links provide no-account client access.
• FastAPI API and a private Google Cloud Run worker.
• Cloud Firestore for runs, versioned baselines, preferences, evidence, review sessions, and append-only audit events.
• Cloud Pub/Sub to hand off long-running and resumed work to the worker, with authenticated push and a dead-letter path.
• Google ADK to structure the agent workflow and narrow its available tools.
• Gemini Developer API using gemini-3.5-flash with gemini-3.6-flash fallback for structured extraction and Guardrail proposals.

The only user data sources are typed project material, client-entered clarification responses, and text/URL evidence supplied in the product. The current scope intentionally does not claim automatic ingestion or analysis of uploaded binary media.

Challenges we ran into

The hardest problem was not technical — it was deciding what the agent is not allowed to do. Gemini can interpret a brief and compare a new request against it, but agreement, versioning, and acceptance must stay deterministic. Drawing that line required a 700-line domain-rules contract (09-DOMAIN-RULES.md) that every backend path obeys, because two agents improvising domain rules independently produce two systems that both "pass tests" but disagree on what was agreed.

On the infrastructure side, Cloud Run session-cookie creation failed silently in production because the API service account was missing roles/firebaseauth.editor — a permission that verify_id_token() does not need but create_session_cookie() does. The failure only appeared after a full Pub/Sub push smoke, not in local testing. We also discovered that every row on the Records page linked to /records/{id}/records instead of the correct section — a bug invisible to TypeScript because the URL was assembled as a template string.

Pub/Sub at-least-once delivery meant duplicate messages were inevitable. We solved idempotency with a deterministic {run_id}:{round} claim key in Firestore, so resumed work after client actions does not collide with the original extraction.

Accomplishments that we're proud of

The final release passed 237 backend tests, 45 frontend unit tests, 9 Playwright browser E2E tests, a clean lint, and a production build — all verified on the same commit that was deployed. A full production end-to-end smoke ran from Firebase custom-token exchange through Gemini extraction, client baseline confirmation, Guardrail classification with a verbatim citation, evidence attachment, delivery review, and proof export — then cleaned up its own temporary Firebase user.

The client never needs an account. A scoped opaque link gives them exactly the actions they need — confirm a plan, answer clarification questions, review delivery — without sign-up friction or accidentally gaining owner access.

The domain rules document is something we would genuinely use on real freelance work. Criterion acceptance carries forward across baseline versions only when the text is unchanged; if the scope changes, only the affected criteria reset. That single rule prevents the most common UX failure in versioned agreements: forcing a client to re-accept everything because one line changed.

What we learned

Restricting the ADK tool surface is more effective than prompt engineering. The agent cannot approve a baseline or accept delivery because those tools simply do not exist in its workflow — not because we told it not to. That makes the guarantee structural, not probabilistic.

Source citations must be validated server-side. Gemini produces plausible deliverables[0] references, but we learned early that the cited field must actually exist in the current baseline. Server-side validation caught several cases where the model cited a field name that was close but not exact.

Append-only event logs make debugging vastly easier than mutable status fields. Every decision — human or agent — is an immutable event with baseline_version + actor + seq. When something looked wrong during the production smoke, we could trace the exact sequence without guessing which update overwrote which.

What's next for Delividence

1. Verified client identity — magic-link email verification or integration with an e-signature provider, so the client link proves who confirmed, not just that someone did.
2. Evidence source adapters — GitHub commit, Figma frame, and Google Drive file adapters that verify artifact metadata deterministically instead of relying on pasted URLs.
3. Side-by-side baseline diff — when the baseline moves from v1 to v2, show exactly what changed and which criteria were affected, with a structured impact summary.
4. Binary media ingestion — Cloud Storage adapter and a multimodal worker path so the agent can process uploaded images, audio, and video instead of only text and referenced URLs.
5. PDF acceptance record — a downloadable summary that includes the manifest hash, acceptance timeline, and clear limitation language for both parties to keep.

Built With

• cloudfirestore
• cloudpub/sub
• docker
• fastapi
• firebaseauthentication
• geminiapi
• googleadk
• googlecloudrun
• gsap
• next.js
• playwright
• pydantic
• python
• react
• secretmanager
• tailwindcss
• typescript
• vercel
• vitest