📚 Quick Navigation

Milestone — App Documentation

Version: 1.1.0
Last updated: November 4, 2025

🧭 Overview

Milestone is a trustless, passwordless SaaS for brokers, consultants, and project managers who share live progress with clients securely — no login required.
It’s built on the ProChat SaaS Boilerplate, integrating magic links, JWT tokens, push notifications, and n8n automation.

New Features (v1.1.0):

• 💬 Client feedback widget on public pages
• 📈 Analytics dashboard with satisfaction trends
• 🔄 Real-time push notifications via service workers
• ⚙️ n8n retry + automation workflows
• 🧩 Secure Clerk mock mode for local development
• 🧾 Schema refactor for milestone tracking and reliability

🚀 Getting Started

Broker Dashboard

https://milestone.prochat.tools/dashboard

• Login via Clerk (Google, Apple, or Email).
• View dossiers, progress, and recent feedback.
• Create new dossiers directly in the dashboard.

Client Public Link

Clients receive a magic link such as:

https://milestone.prochat.tools/l/<jwt_token>

This opens a read-only dossier with:

• Progress bar
• Timeline of milestones
• “Request callback” and “Send feedback” actions

⚙️ Architecture Overview

🔐 Trustless Access Model

JWT Scopes Example:

{
  "sub": "cmhjk1olx0000nv1pl68j1m4d",
  "jti": "7fd89e08-8564-4f86-a7d3-bfdca449d1b5",
  "scopes": ["read:public"],
  "exp": 1763409038
}

Middleware whitelists:

publicRoutes: [
  '/l(.*)', '/api/push/subscribe', '/', '/favicon.ico'
]

💬 Client Feedback

Clients can rate their experience at the bottom of their public milestone page.

Feedback Widget

• 👍 “Satisfied”
• ⚠️ “Needs Attention”
• 💬 Optional comment

Endpoint:

POST /api/feedback

Body:

{
  "token": "<public_link_jwt>",
  "rating": "satisfied",
  "comment": "Smooth process and fast response!"
}

Brokers can view all client feedback directly in /d/:id.

📈 Analytics Dashboard

Brokers now see visual insight into performance and satisfaction:

Metrics:

• Total dossiers
• Active vs completed
• Satisfaction ratio (positive vs negative feedback)
• 30-day satisfaction trend (Recharts line + pie visualization)

Endpoint Source: /lib/analytics.ts

🔔 Notifications & n8n

Web Push

Clients can subscribe to browser push notifications.
Triggered events include:

• Milestone completion
• Callback requests
• Negative feedback alerts

n8n Automations

Configured automations include:

• 🕗 Daily stale dossier reminder
• 🔁 Retry failed webhooks via N8nRetry table
• 📧 Weekly summary digest

Example n8n Workflow

{
  "name": "Milestone - Stale Reminder",
  "nodes": [
    { "id": "1", "type": "cron", "parameters": { "rule": "0 8 * * *" } },
    { "id": "2", "type": "httpRequest", "parameters": {
        "url": "https://milestone.prochat.tools/api/n8n/retry",
        "method": "GET",
        "headers": { "x-api-key": "YOUR_N8N_API_KEY" }
    }}
  ]
}

🧾 Testing Checklist

🧱 Deployment Notes

Dokploy Configuration

DATABASE_URL="postgresql://postgres:postgres@dokploy-postgres:5432/db?schema=milestone"
NEXT_PUBLIC_APP_URL="https://milestone.prochat.tools"
N8N_WEBHOOK_URL="https://automation.prochat.tools/webhook"
N8N_API_KEY="your-secure-api-key"

Deploy commands:

npx prisma migrate deploy
dokploy up milestone

🕓 Version History

📬 Contact & Support

📧 support@prochat.tools
🌐 https://docs.prochat.tools
💡 Feedback and issues welcome on GitHub.