# Permit Pal: Decode Your Home Project Paperwork ## The Problem Homeowners in Springfield face a 47-page municipal code just to understand if their back deck needs a permit. The city's permit office uses terms like "setback variance," "lot coverage ratio," and "conditional use authorization" without explanation—language designed for contractors, not regular people. As a result, simple home improvement projects either get abandoned, done illegally (risking fines), or require hiring a $200/hour consultant just to translate the paperwork. ## Who Uses It **Maria, 34, First-time Homeowner**: Just bought a house with a rotting porch. She's handy enough to rebuild it herself but has no idea if she needs a permit, what inspections are required, or whether she'll accidentally violate some code about railings. She Googled "Springfield porch permit" and got lost in PDFs. **Dave, 58, DIY Dad**: Wants to build his grandkids a treehouse in the backyard. He's built treehouses before in other states but heard Springfield has specific rules about accessory structures. He'd rather ask a question in plain English than dig through municipal code sections. **The Chen Family**: Planning to add a 6-foot privacy fence between their yard and a busy street. They've heard horror stories about neighbors having to tear down fences that were 6 inches too tall or 2 feet too close to the sidewalk. ## Core Features 1. **Plain-English Project Describer**: Users type what they want to do naturally ("I want to build a 12x10 wooden deck off my back door") and the system identifies relevant permit categories, no jargon required. 2. **Permit Checklist Generator**: Based on the project description and city services data, generates a step-by-step checklist: which forms to file, in what order, estimated fees, and typical processing times. 3. **Jargon Translator**: When official permit language is unavoidable, each term gets a hover/tap definition in plain English. "Setback" becomes "how far your project must be from property lines." 4. **Ask Ody for Edge Cases**: Users can ask follow-up questions ("What if my lot is on a corner?" "Does a pergola count as a structure?") and get contextual responses drawing from civic services knowledge. 5. **Common Gotchas Alert**: For each project type, display the 3-5 most common mistakes that delay permits or require re-work—knowledge that usually lives only in contractors' heads. 6. **Local Office Finder**: Show which city office handles each permit type, with contact info and hours pulled from civic services data, so users know exactly where to go. 7. **Save & Share Project Plans**: Users can save their project and checklist to return to later, or share a link with a spouse/partner who also needs to understand the process. ## WellSpr.ing Integration Points ### MCP Tools (via POST to https://wellspr.ing/mcp using JSON-RPC 2.0) | Tool | Usage | |------|-------| | `get_city_services` | Primary data source—pull permit office info, building department contacts, zoning resources, and official permit requirement pages | | `search_civic_services` | Query specific permit types ("deck permit," "fence permit," "building inspection") to find relevant city services and forms | | `ask_ody` | Power the conversational Q&A—users describe their project or ask follow-ups, Ody synthesizes civic services data into plain-language guidance | | `get_businesses` | Find licensed contractors or permit expediting services if users decide they do want professional help | | `get_business_detail` | Show details about recommended local contractors including contact info | ### REST Endpoints | Endpoint | Usage | |----------|-------| | `GET /api/officials` | Display relevant city officials (building inspector, zoning administrator) users might need to contact for complex cases | | `GET /api/geo/portals?area_code=NNN` | If expanding to multiple municipalities, identify which civic portal serves the user's area | ### WCIB Integration | Endpoint | Usage | |----------|-------| | `GET /api/wcib/ideas` | Show related civic tech ideas users might want to support or build (community tool libraries, neighborhood improvement grants) | | `POST /api/wcib/ody-ask` | Alternative path for Ody queries from WCIB context | ### Future Capabilities (Roadmap: not yet live) - **Permit fee calculator API**: Would allow real-time fee estimates based on project scope - **Form pre-fill integration**: Would let users populate official city forms directly from their project description - **Inspection scheduling**: Would enable booking required inspections through the app ## Data Model ``` ┌─────────────────────────┐ │ projects │ ├─────────────────────────┤ │ id (uuid, pk) │ │ user_session_id (text) │ │ description (text) │ ← User's plain-English project description │ project_type (text) │ ← Categorized: deck, fence, porch, shed, etc. │ created_at (timestamp) │ │ updated_at (timestamp) │ └─────────────────────────┘ ┌─────────────────────────┐ │ permit_checklists │ ├─────────────────────────┤ │ id (uuid, pk) │ │ project_id (fk) │ │ checklist_json (jsonb) │ ← Generated steps, fees, contacts │ gotchas_json (jsonb) │ ← Common mistakes for this project type │ generated_at (timestamp)│ └─────────────────────────┘ ┌─────────────────────────┐ │ conversations │ ├─────────────────────────┤ │ id (uuid, pk) │ │ project_id (fk) │ │ question (text) │ │ ody_response (text) │ │ asked_at (timestamp) │ └─────────────────────────┘ ┌─────────────────────────┐ │ jargon_definitions │ ├─────────────────────────┤ │ term (text, pk) │ ← "setback", "variance", "lot coverage" │ plain_definition (text) │ ← "How far your project must be from..." │ related_terms (text[]) │ └─────────────────────────┘ ``` ## Vibe Coding Prompt to Get Started Paste this into Claude or Replit Agent: ``` Build a civic tech web app called "Permit Pal" that helps homeowners understand city permit requirements in plain English. TECH STACK: - React frontend with Tailwind CSS - Express.js backend on Node - SQLite database (simple, no setup) - Deploy on Replit FIRST MILESTONE - "Describe & Decode" (aim for 2-3 hours): 1. Create a single-page React app with a friendly, approachable design (think: helpful neighbor, not government bureaucracy). Use warm colors and clear typography. 2. Build the main input component: a large text area where users describe their project naturally. Include placeholder text: "Tell us about your project... Example: I want to build a 10x12 foot wooden deck attached to my back door, about 2 feet off the ground." 3. Add a "Decode My Project" button that: - Sends the description to your Express backend - Backend calls the W