---

/ | | | | _ \
| ( ___ _ __ ___ | | | |) | ___ ___ ___ _ __
_ \ / _ | '_ ` _ \ / _ \ | | _ < / _ / / _ | ' \ ) | () | | | | | | _/ | | |) | __/ (| () | | | | |/ _/|| || ||___|_| |__/ _|____/|| ||

Smart Proposal

Helping teams deliver polished proposals with AI-assisted storytelling and accurate quotes.

Vision

Smart Proposal brings every part of the proposal lifecycle into one place so creative, sales, and operations teams can move faster together. From the first intake conversation to the final PDF handoff, the product keeps context connected and elevates every client touchpoint.

Our north star is a confident, repeatable process: collect the right details once, let AI draft a compelling narrative, fine-tune quotes with clarity, and share results through a delightful, branded experience.

Roadmap Highlights

• Phase 01 - Unified Workspace. Establish a shared home for the web app, service layer, and reusable building blocks so every contributor works from the same playbook.
• Phase 02 - Trusted Accounts & Data. Launch a secure hub for team members, proposals, and quote records, backed by authentication and thoughtful data policies.
• Phase 03 - Core Services. Introduce reliable services that coordinate proposal and quote actions, ensuring every request is validated, auditable, and ready for future automation.
• Phase 04 - AI Proposal Generation. Teach the platform to co-write proposals by blending project inputs with curated prompts, producing structured sections that stay on brand.
• Phase 05 - Proposal Experience. Craft a focused dashboard and editing flow where teams can create, review, and refine proposals with live AI assistance.
• Phase 06 - Quote Calculator. Embed an interactive quote workspace that keeps pricing, taxes, and totals accurate while syncing effortlessly into each proposal.
• Phase 07 - PDF & Sharing. Offer polished, branded exports and controlled share links so clients can review proposals securely on any device.
• Phase 08 - Insights Dashboard. Surface key metrics around proposal activity, client engagement, and AI usage to guide teams toward smarter follow-ups.

Guiding Principles

• People-first storytelling that balances automation with human voice.
• One source of truth so every team member trusts the latest proposal and quote data.
• Transparent AI usage with clear prompts, guardrails, and fallback paths.
• Built to grow, with each phase setting up the next wave of features and partnerships.

How to Explore

The .plans directory outlines each phase in depth—perfect for onboarding, planning sprints, or scoping contributions. Start with Phase 01 to understand the foundation, then follow the phases in sequence to see how Smart Proposal evolves into a complete client-ready platform.

Workspace at a Glance

• apps/web: Next.js frontend shell with a shared UI button to prove package wiring.
• apps/api: Express server stub exposing /health and /api/proposals for future services.
• packages/ui: React component library seed (currently exports a styled button).
• packages/utils: Shared helpers, including Supabase clients, available to all workspaces.

Getting Started

1. Install dependencies: pnpm install
2. Run local development servers in parallel: pnpm dev
3. Check quality gates:
   • Lint: pnpm lint
   • Type safety + builds: pnpm build

Environment variables live in .env files (see .env.example). Default ports are 3000 for the web app and 4000 for the API.

API Service

• Location: apps/api
• Core endpoints:
  • GET /api/proposals — list proposals for the authenticated user (optional status filter)
  • POST /api/proposals — create a proposal
  • PUT /api/proposals/:proposalId — update proposal details or content
  • GET /api/proposals/:proposalId/quotes — retrieve quotes tied to a proposal
  • POST /api/proposals/:proposalId/quotes — create or update quote line items and totals
  • POST /api/generate — trigger AI-assisted generation (mode: full | section)
  • Frontend requests use NEXT_PUBLIC_API_URL (defaults to http://localhost:4000) to target the API gateway.
• Auth: provide a Supabase access token via Authorization: Bearer <token> header.
• Reference apps/api/requests.http for ready-to-run examples (REST Client / Thunder Client compatible).

Supabase Setup

Supabase powers authentication, proposal storage, and quote management.

• Prerequisites
  • Install the Supabase CLI: pnpm dlx supabase@latest init (first run) and pnpm dlx supabase@latest --help for upgrades.
  • Ensure Docker is available if you plan to run the local stack.
• Project configuration
  • Update supabase/config.toml with your hosted project project_id and organization_id.
  • Copy .env.example to .env, then supply NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, and the secure SUPABASE_SERVICE_ROLE_KEY.
• Local workflow
  1. Start the local stack: pnpm dlx supabase start
  2. Apply migrations: pnpm dlx supabase db reset (recreates the database and runs everything in supabase/migrations)
  3. Seed data (optional): pnpm dlx supabase db reset --seed supabase/seed.sql
• Using the utilities
  • packages/utils exports createSupabaseBrowserClient and createSupabaseServerClient for consistent client creation.
  • Typed helpers such as listProposalsForUser and upsertQuote encapsulate common queries against the shared schema.

Keep the service role key on the server only. Frontend code should consume the browser client helpers which rely on the anon key.

AI Generation

• The backend uses OpenAI’s Responses API to draft proposal sections.
• Required environment variables (see .env.example):
  • OPENAI_API_KEY
  • OPENAI_MODEL (optional, defaults to gpt-4.1-mini)
• POST /api/generate
  • mode: "full" — supply generation inputs (projectName, projectSummary, etc.) to create all sections
  • mode: "section" — supply rewrite inputs (section, existingContent, projectSummary) to refresh a single section
  • Optional settings allow custom model or temperature
• Generated output is written back to proposals.content for later retrieval by the frontend.