@soulcraft/kits 1.0.0

package/kits/invoice-generator/kit.json

@@ -0,0 +1,466 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "invoice-generator",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "Invoice Generator",
+  "description": "Create professional invoices, track payments, and manage client billing",
+  "longDescription": "A full-featured invoicing app built on SvelteKit and Brainy. Manage clients and projects, build detailed invoices with line items and tax, track payment status, and generate PDF-ready output. Brainy powers the client and invoice knowledge graph, linking every payment back to its source invoice and client so you always know who owes what.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "🧾",
+  "tags": [
+    "invoicing",
+    "billing",
+    "clients",
+    "payments",
+    "freelance",
+    "finance"
+  ],
+  "variables": [
+    {
+      "key": "businessName",
+      "label": "Business Name",
+      "description": "Your business or freelance trading name shown on all invoices",
+      "type": "string",
+      "required": true,
+      "example": "Apex Creative Studio"
+    },
+    {
+      "key": "businessEmail",
+      "label": "Business Email",
+      "description": "Contact email printed on invoice footers and quote headers",
+      "type": "email",
+      "required": true,
+      "example": "hello@apexcreative.studio"
+    },
+    {
+      "key": "businessAddress",
+      "label": "Business Address",
+      "description": "Full mailing address shown on invoices for legal and tax purposes",
+      "type": "string",
+      "required": false,
+      "example": "42 Harbour Street, Suite 7, Sydney NSW 2000"
+    },
+    {
+      "key": "taxRate",
+      "label": "Default Tax Rate (%)",
+      "description": "Percentage applied to taxable line items (e.g. 10 for 10% GST or VAT). Enter 0 to disable tax.",
+      "type": "number",
+      "required": false,
+      "example": "10",
+      "default": "0"
+    },
+    {
+      "key": "currencySymbol",
+      "label": "Currency Symbol",
+      "description": "Symbol displayed next to monetary amounts on invoices and quotes",
+      "type": "string",
+      "required": false,
+      "example": "$",
+      "default": "$"
+    },
+    {
+      "key": "invoicePrefix",
+      "label": "Invoice Number Prefix",
+      "description": "Short prefix prepended to auto-incrementing invoice numbers (e.g. INV-0001)",
+      "type": "string",
+      "required": false,
+      "example": "INV",
+      "default": "INV"
+    },
+    {
+      "key": "paymentTerms",
+      "label": "Default Payment Terms",
+      "description": "Standard payment terms printed on invoices unless overridden per client",
+      "type": "string",
+      "required": false,
+      "example": "Net 30",
+      "default": "Net 30"
+    }
+  ],
+  "shared": {
+    "industry": "business-finance",
+    "category": "business",
+    "glossary": {
+      "invoice": "A formal request for payment sent to a client after work is completed, listing services rendered and the total amount due.",
+      "line item": "A single charge on an invoice representing one unit of work, product, or expense with a quantity, rate, and subtotal.",
+      "net 30": "Payment terms requiring the client to pay within 30 calendar days of the invoice date.",
+      "deposit": "An upfront partial payment — typically 25–50% — collected before work begins to secure the engagement.",
+      "retainer": "A recurring pre-payment arrangement where a client pays a fixed amount each month for a guaranteed block of hours or services.",
+      "billable hours": "Time spent on client work that is eligible to be charged back to the client at an agreed hourly rate."
+    },
+    "aiExpertise": [
+      "invoice structure and professional billing practices",
+      "tax calculation and jurisdiction-specific rules",
+      "payment terms, deposits, and retainer agreements",
+      "cash flow management and accounts receivable",
+      "client relationship and billing communication",
+      "quote-to-invoice conversion workflows",
+      "late payment handling and collection strategies"
+    ],
+    "dataModelHints": [
+      "client",
+      "invoice",
+      "line_item",
+      "payment",
+      "quote"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "client",
+          "type": "Person",
+          "description": "A business or individual who commissions work and receives invoices. Stores contact details, billing address, payment terms override, and outstanding balance.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "👤"
+            },
+            "academy": {
+              "mapsTo": "learner",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "invoice",
+          "type": "Document",
+          "description": "A formal payment request issued to a client. Records issue date, due date, payment terms, line items, tax, and payment status.",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "🧾"
+            },
+            "academy": {
+              "mapsTo": "learning-artifact",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "line_item",
+          "type": "Thing",
+          "description": "A single billable row on an invoice or quote. Contains description, quantity, unit rate, and taxable flag.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "📋"
+            }
+          }
+        },
+        {
+          "domain": "payment",
+          "type": "Event",
+          "description": "A recorded payment against an invoice — partial or full. Stores amount in cents, payment method, and received date.",
+          "products": {
+            "workshop": {
+              "view": "timeline",
+              "icon": "💳"
+            },
+            "academy": {
+              "mapsTo": "practice-session",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "quote",
+          "type": "Document",
+          "description": "A pre-invoice estimate sent to a prospective client for approval before work begins. Can be converted to an invoice once accepted.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "📝"
+            },
+            "academy": {
+              "mapsTo": "learning-artifact",
+              "assessable": false
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "client",
+          "to": "invoice",
+          "verb": "Creates",
+          "description": "Client is billed via one or more invoices over the course of the engagement."
+        },
+        {
+          "from": "client",
+          "to": "quote",
+          "verb": "Creates",
+          "description": "Client receives a quote before work is approved and invoicing begins."
+        },
+        {
+          "from": "invoice",
+          "to": "line_item",
+          "verb": "Contains",
+          "description": "Invoice breaks down the total charge into individual service or product line items."
+        },
+        {
+          "from": "quote",
+          "to": "line_item",
+          "verb": "Contains",
+          "description": "Quote lists estimated line items that become invoice line items upon acceptance."
+        },
+        {
+          "from": "payment",
+          "to": "invoice",
+          "verb": "References",
+          "description": "Payment records the amount received against a specific invoice, updating its balance due."
+        },
+        {
+          "from": "invoice",
+          "to": "quote",
+          "verb": "References",
+          "description": "Invoice references the accepted quote it was converted from, preserving the approval trail."
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Create an invoice",
+        "prompt": "Help me create a new invoice for a client with line items, tax, and payment terms."
+      },
+      {
+        "label": "Track a payment",
+        "prompt": "Record a payment received for an outstanding invoice and update its balance."
+      },
+      {
+        "label": "Draft a quote",
+        "prompt": "Help me put together a project quote to send to a new client for approval."
+      },
+      {
+        "label": "Review outstanding invoices",
+        "prompt": "Show me all unpaid invoices and flag any that are past their due date."
+      },
+      {
+        "label": "Add a new client",
+        "prompt": "Add a new client with their billing address, email, and default payment terms."
+      },
+      {
+        "label": "Analyse revenue",
+        "prompt": "Summarise my invoiced revenue by client and month for the past quarter."
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "business-finance",
+    "level": "beginner",
+    "learningObjectives": [
+      "Create professional client invoices with correctly structured line items, subtotals, tax, and due dates",
+      "Track payment status across outstanding, partially paid, and fully settled invoices",
+      "Manage a client roster with per-client billing preferences and payment history",
+      "Calculate and apply tax rates correctly to taxable line items",
+      "Organise billing history and generate summary views of revenue earned per client or period"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "invoice-creator"
+  },
+  "workshop": {
+    "difficulty": "intermediate",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are a financial assistant helping freelancers and small business owners create professional invoices and track client payments. You know billing conventions, tax rules, and cash flow best practices inside out.",
+      "expertise": [
+        "client billing and accounts receivable",
+        "tax calculation and jurisdiction rules",
+        "payment terms, deposits, and retainer structures",
+        "cash flow management and late payment handling",
+        "quote-to-invoice conversion workflows",
+        "professional invoice design and legal requirements"
+      ],
+      "tone": "collaborator",
+      "avoidances": [
+        "Don't give specific tax or legal advice — recommend consulting a local accountant for jurisdiction-specific questions",
+        "Don't assume a currency unless the user has set one in their variables",
+        "Don't invent client details — always ask the user to supply real contact information"
+      ]
+    },
+    "workspaceConfig": {
+      "paradigm": "analyst",
+      "defaultTab": "app",
+      "defaultView": "app"
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "client name or company mentioned",
+          "invoice number or billing event referenced",
+          "payment received or recorded",
+          "quote or estimate requested",
+          "line item, service, or product described"
+        ],
+        "typeMapping": {
+          "client": "person",
+          "company": "person",
+          "invoice": "document",
+          "quote": "document",
+          "estimate": "document",
+          "payment": "event",
+          "line item": "thing",
+          "service": "thing",
+          "expense": "thing"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "client",
+          "to": "invoice",
+          "verb": "Creates",
+          "description": "Client receives the invoice"
+        },
+        {
+          "from": "invoice",
+          "to": "line_item",
+          "verb": "Contains",
+          "description": "Invoice holds the billable breakdown"
+        },
+        {
+          "from": "payment",
+          "to": "invoice",
+          "verb": "References",
+          "description": "Payment settles or partially covers the invoice"
+        }
+      ],
+      "rules": [
+        "Every invoice must link to a client",
+        "Every payment must reference the invoice it settles",
+        "Line items must belong to an invoice or quote — never free-floating",
+        "Amounts are always stored in cents; display formatting is a UI concern"
+      ]
+    },
+    "qualityGates": {
+      "projectChecks": [
+        "App starts and the invoice list loads without errors",
+        "A new invoice can be created with at least one line item",
+        "Tax is calculated correctly when a non-zero tax rate is set",
+        "Payment status updates when a payment is recorded against an invoice",
+        "PDF-ready layout renders cleanly for a completed invoice"
+      ],
+      "exportReady": [
+        "No TypeScript errors",
+        "Invoice PDF output is correctly formatted",
+        "All routes load without runtime errors"
+      ]
+    },
+    "templateMetadata": {
+      "identifyByStructure": true,
+      "runnable": true,
+      "runnableCommand": "npm run dev"
+    },
+    "deploy": {
+      "provider": "cloud-run",
+      "buildCommand": "npm run build",
+      "outputDir": "build",
+      "config": {
+        "port": 3000,
+        "memory": "512Mi"
+      },
+      "oneClickCommand": "gcloud run deploy"
+    },
+    "publishConfig": {
+      "contentType": "app",
+      "publishable": true
+    },
+    "sampleData": {
+      "description": "Sample clients and a realistic invoice with line items to demonstrate the app",
+      "entities": [
+        {
+          "type": "person",
+          "name": "Meridian Digital",
+          "properties": {
+            "contactName": "Jessica Park",
+            "email": "jessica@meridiandigital.co",
+            "phone": "+1-555-0182",
+            "address": "1200 Market St, San Francisco CA 94102",
+            "paymentTerms": "Net 30",
+            "status": "active"
+          }
+        },
+        {
+          "type": "person",
+          "name": "Lumen Ventures",
+          "properties": {
+            "contactName": "Carlos Rivera",
+            "email": "c.rivera@lumenventures.io",
+            "phone": "+1-555-0247",
+            "address": "88 Pine Ave, Austin TX 78701",
+            "paymentTerms": "Net 14",
+            "status": "active"
+          }
+        },
+        {
+          "type": "document",
+          "name": "INV-0001",
+          "properties": {
+            "client": "Meridian Digital",
+            "issueDate": "2026-01-15",
+            "dueDate": "2026-02-14",
+            "status": "unpaid",
+            "subtotal": 420000,
+            "taxAmount": 42000,
+            "total": 462000,
+            "notes": "Thank you for choosing Apex Creative Studio."
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "Meridian Digital",
+          "verb": "Creates",
+          "to": "INV-0001"
+        }
+      ]
+    },
+    "remoteWorkspace": {
+      "connectedWorkbenches": [
+        {
+          "name": "Invoice Pipeline",
+          "view": "board",
+          "entityTypes": [
+            "invoice"
+          ],
+          "description": "Drag invoices across Draft, Sent, Partially Paid, and Paid columns"
+        },
+        {
+          "name": "Client Roster",
+          "view": "gallery",
+          "entityTypes": [
+            "client"
+          ],
+          "description": "Browse clients, their outstanding balances, and payment history"
+        },
+        {
+          "name": "Revenue Timeline",
+          "view": "timeline",
+          "entityTypes": [
+            "payment",
+            "invoice"
+          ],
+          "description": "Visualise cash received versus invoices issued over time"
+        },
+        {
+          "name": "Billing Graph",
+          "view": "graph",
+          "entityTypes": [
+            "client",
+            "invoice",
+            "payment"
+          ],
+          "description": "Graph connecting clients to their invoices and recorded payments"
+        }
+      ]
+    }
+  }
+}