Deployment Documentation

Updated: Fri 12 Jun 2026 — Added Monitoring section (Neo4j keepalive + Aura free-tier capacity tracking)

This directory documents how the Plings services are built and deployed. All current cloud services run on Vercel:

Service	Disk path	Vercel runtime	URL
Plings-API	Plings-API/	Serverless Functions	api.plings.io
Plings-Gateway	Plings-Gateway/	Edge	s.plings.io
Plings-Web	Plings-Web/	CDN (static build)	plings.io

Native iOS / Android apps (planned — Plings-iOS, Plings-Android) will distribute through the App Store and Play Store; their deployment is out of scope for this directory.

Documents

• Deployment Procedures — build and deploy steps per service
• Environment Configuration — required environment variables across all services
• CI/CD Pipeline — GitHub Actions and Vercel integration

Monitoring

A full observability stack (OpenTelemetry, Grafana/Loki) is still on the roadmap. What exists today:

Neo4j keepalive + capacity (/cron/neo4j-keepalive)

A Vercel cron in Plings-API (vercel.json → crons, daily at 05:00 UTC) hits /cron/neo4j-keepalive. It serves two purposes:

1. Keepalive — a daily read keeps the Aura free-tier instance from auto-pausing (3 idle days) and being auto-deleted (30 paused days). The first Aura instance was lost exactly this way in June 2026.
2. Capacity tracking — Aura Free caps the graph at 200 000 nodes / 400 000 relationships (verified Jun 2026 via the Neo4j FAQ; Neo4j’s product page inconsistently still lists the original 2021 figures of 50k/175k). Writes start failing once the ceiling is reached, so the cron counts nodes and relationships each run and classifies usage:
   • ok below 75%
   • warning at ≥ 75% → logger.warning
   • critical at ≥ 90% → logger.error

   The metrics are also returned in the endpoint’s JSON response (capacity object) for any external monitor that polls it.

Where to look: Vercel → Plings-API project → Logs. Filter for Neo4j capacity to see the daily reading; a 🚨 ... CRITICAL or ⚠️ ... WARNING line means it’s time to upgrade the Aura tier. Delivery is log-only today — there is no push notification yet. To add one later: have the cron return a non-2xx on critical (Vercel emails the project owner on cron failure), or send via an email API such as Resend.

Tuning (Plings-API Vercel env, all optional — defaults shown): | Variable | Default | Purpose | |———-|———|———| | NEO4J_MAX_NODES | 200000 | Free-tier node ceiling | | NEO4J_MAX_RELATIONSHIPS | 400000 | Free-tier relationship ceiling | | NEO4J_CAPACITY_WARN | 0.75 | Fraction → WARNING | | NEO4J_CAPACITY_CRITICAL | 0.90 | Fraction → CRITICAL |

If usage stalls below the configured limit (Aura rejecting writes earlier than expected), lower NEO4J_MAX_* to the real enforced figure from the Aura console — no redeploy needed.

Database health (/health/db)

Reports Postgres + Neo4j connectivity. Known issue: currently errors with 'NullPool' object has no attribute 'size' in the serverless pool — fix pending.

Supabase advisors

Run get_advisors (security + performance) after any schema change. See SCHEMA-VERIFICATION.md.