Files · Lien Waiver Collector for Specialty Trade Contractors

# Lien Waiver Collector for Specialty Trade Contractors
 
> Automate lien waiver collection per draw with automated reminders and audit trail.
 
A project manager at a specialty trade contractor (e.g., electrical or plumbing) spends hours every week chasing lien waivers from subs before each draw request. Subcontractors ignore emails, and missing waivers delay payments. This system sends automated requests, tracks status, and stores signed waivers with timestamps.
 
## Problem
 
Trade contractors must collect signed lien waivers from every subcontractor before each draw request. Without automation, this is a manual, error-prone process of emailing subs, tracking replies in spreadsheets, and filing paper documents — often delaying payments by weeks.
 
## Features
 
- **Automated waiver requests** — Create and send lien waivers for signature via DocuSign
- **AI-powered reminders** — Draft polite, escalating reminder messages using the Vercel AI SDK (OpenAI / DeepSeek)
- **Status tracking** — Full audit trail of every state transition (sent → reminded → signed)
- **Signed document storage** — Signed waivers stored in Vercel Blob with signed URLs
- **Idempotent API** — Safe retry for POST/PUT requests via `@reaatech/idempotency-middleware`
- **Validation pipeline** — Pre-send content validation via `@reaatech/guardrail-chain`
- **Observability** — LLM call tracing via Langfuse
- **Dashboard** — Real-time status overview of waivers, projects, and subcontractors
 
## Architecture
 
This recipe demonstrates a **document-pipeline** architecture:
 
1. A PM creates a waiver task for a subcontractor on a project draw
2. The waiver content is validated by a guardrail chain (`@reaatech/guardrail-chain`)
3. A DocuSign envelope is sent to the subcontractor for eSignature (`docusign-esign`)
4. Automated reminders are drafted by the Vercel AI SDK and sent on a schedule
5. A DocuSign Connect webhook updates the waiver status when signed
6. The signed PDF is stored in Vercel Blob (`@vercel/blob`)
7. Every state transition is logged via the A2A task store (`@reaatech/a2a-reference-persistence`)
8. Waiver events are persisted in agent memory (`@reaatech/agent-memory-storage`)
9. All LLM interactions are traced in Langfuse (`langfuse`)
10. API endpoints are secured by API key auth (`@reaatech/a2a-reference-auth`) and idempotent (`@reaatech/idempotency-middleware`)
 
## Tech Stack
 
| Layer | Technology |
|-------|-----------|
| Frontend UI | Next.js 16 (App Router) |
| API Server | Hono |
| Language | TypeScript (strict) |
| Schema Validation | Zod |
| AI SDK | Vercel AI SDK (`ai` + `@ai-sdk/openai`) |
| Provider | OpenAI / DeepSeek (agnostic fallback) |
| eSignature | DocuSign (`docusign-esign`) |
| File Storage | Vercel Blob (`@vercel/blob`) |
| Observability | Langfuse (`langfuse`) |
| Task Persistence | `@reaatech/a2a-reference-persistence` |
| Authentication | `@reaatech/a2a-reference-auth` |
| Agent Memory | `@reaatech/agent-memory-storage` |
| Idempotency | `@reaatech/idempotency-middleware` |
| Guardrails | `@reaatech/guardrail-chain` |
| Response Schemas | `@reaatech/mcp-server-core` |
| Testing | Vitest + MSW |
 
## Getting Started
 
```bash
# Install dependencies
pnpm install
 
# Copy environment variables
cp .env.example .env.local
# Edit .env.local with your API keys (OpenAI, DocuSign, Vercel Blob, Langfuse)
 
# Start the development server (Hono API on :3001 + Next.js on :3000)
pnpm dev
 
# Run tests with coverage
pnpm test
```
 
## Project Layout
 
```
app/                  Next.js App Router pages (dashboard, projects, waivers)
src/
  lib/                Core types, Zod schemas, constants, API client
  services/           Business logic wrappers (persistence, auth, memory, idempotency,
                      guardrail, mcp, docusign, blob, ai, langfuse)
  server/             Hono API server + route definitions
  middleware/         Auth middleware
tests/                Vitest suite (172 tests, 90%+ coverage)
packages/             API references for every dependency
DEV_PLAN.md           Build plan
```
 
## Testing
 
```bash
pnpm test            # 172 tests, 99% lines, 91% branches, 97% functions, 98% statements
pnpm typecheck       # TypeScript strict mode
pnpm lint            # ESLint flat config
```
 
## License
 
MIT — see [LICENSE](./LICENSE).