Lawmedy

A private workspace for legal notices, RTI applications, and ₹199 lending certificates, with web and Expo mobile clients, private evidence, grounded AI drafting/QA, Razorpay payments, advocate review and private PDF delivery.

The current hosting plan is Hostinger for the Next.js website and DigitalOcean for the Nest API, PostgreSQL and Caddy. Follow docs/deploy-vps.md for deployment, environment values, Razorpay setup, mobile rebuilds, and the advocate's signed-certificate workflow. See the security review and operations plan before launch.

Adding valid RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET to the API environment automatically replaces the old manual payment flow on both clients. Configure the signed payment.captured webhook before going live so payments still complete after checkout is closed. Only captured payments start document work.

Lending certificates record money already paid or lent. The in-house advocate reviews the facts and uploads the final signed and stamped PDF on their letterhead; ordinary approval and automatic PDF generation cannot bypass that upload. Delivery is within 24 hours of verified payment and complete information. This product is a lending record, not an affidavit or notarisation. Its price comes from LENDING_CERTIFICATE_PRICE_PAISE=19900.

Requirements

• Node.js 22 or 24 LTS
• pnpm 10.30.3 (corepack enable, or use corepack pnpm in place of pnpm)
• Docker Desktop with Compose running, or an existing PostgreSQL server

Local setup (PowerShell)

Copy-Item .env.example .env
Copy-Item apps/api/.env.example apps/api/.env
Copy-Item apps/web/.env.example apps/web/.env

Choose a local database password and put the same value in the root POSTGRES_PASSWORD and the API DATABASE_URL (URL-encode special characters in the URL). Set the API's JWT_SECRET to a random value of at least 32 characters; placeholder secrets are rejected. You can generate one with:

node -e "console.log(require('node:crypto').randomBytes(48).toString('hex'))"

Add a Google AI Studio key to apps/api/.env as GEMINI_API_KEY. The key stays server-side. AI_PROVIDER=gemini and GEMINI_MODEL=gemini-3.8-flash are configuration values and can be changed without modifying application code. The application still starts and accepts private uploads when the key is empty: AI analysis shows a retryable failure instead of crashing.

Evidence files default to apps/api/.local/private-files (or the API process's equivalent working directory) and are ignored by Git. Set PRIVATE_STORAGE_DIR to an absolute path in production. EVIDENCE_MAX_BYTES defaults to 10 MB. FILE_SIGNING_SECRET should be a separate random value of at least 32 characters; local development falls back to JWT_SECRET when it is omitted.

The legal-notice price is configured in paise using LEGAL_NOTICE_PRICE_PAISE (default 29900, meaning ₹299). For Razorpay test mode, add RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, and a separate RAZORPAY_WEBHOOK_SECRET to apps/api/.env. Configure Razorpay’s payment.captured webhook to call https://your-api.example/payments/razorpay/webhook. Missing Razorpay values leave review available and show a payment-setup message instead of crashing.

Then:

pnpm install
docker compose up -d --wait
pnpm db:generate
pnpm db:migrate
pnpm --filter @lawmedy/api db:seed
pnpm dev

The seed command creates the local advocate from ADVOCATE_EMAIL, ADVOCATE_FULL_NAME, and ADVOCATE_PASSWORD in apps/api/.env. Copy the placeholders from apps/api/.env.example, replace the password for your own environment, run the seed command, then sign in at /login. Advocate accounts are sent to the role-protected /advocate workspace.

Legal-notice and RTI final PDFs are drawn with pdfkit using the Noto fonts in apps/api/assets/fonts (Hindi text uses Noto Serif Devanagari). No browser or system fonts are needed. The API runs on the shared DigitalOcean droplet; see docs/deploy-shared-droplet.md.

Email delivery uses Resend. For sandbox testing, put RESEND_API_KEY and a verified RESEND_FROM sender in apps/api/.env. When these values are absent, advocate approval still creates the private PDF and completes the matter; the user sees the download in Lawmedy with a clear local email-configuration note.

Open localhost:3000. The Nest API runs at http://127.0.0.1:4000. If pnpm is not on PATH, all commands work as corepack pnpm …. If Docker is unavailable, provision PostgreSQL and set DATABASE_URL before running migrations. Do not use docker compose down -v unless you intend to delete the database; normal docker compose down preserves it.

If Turborepo reports that it cannot find the package manager, run corepack enable --install-directory node_modules/.bin after installation. This creates project-local pnpm shims without changing the system installation.

Optional local PostgreSQL without Docker

For a fresh checkout without Docker, run node scripts/local-db.mjs after pnpm install, before copying an API .env. This development-only helper runs real PostgreSQL 17 on loopback port 5433 and creates apps/api/.env with random local credentials and a JWT secret. It never overwrites an existing .env. Keep that terminal running, then run pnpm db:generate, pnpm db:migrate, and pnpm dev in a second terminal. Ctrl+C stops PostgreSQL and preserves data in the ignored .local/ directory. Restart using the same command. The bundled helper is a beta npm wrapper around PostgreSQL; Docker Compose remains the standard setup. Do not sync or commit .local/ or use this helper for production.

Verify

1. Create an account at /signup and check that the dashboard opens.
2. Click New Legal Notice, then Create matter & continue. Creation is a POST from a confirmation form, never an accidental GET during link prefetching.
3. Describe a situation such as “I lent someone ₹50,000 in March and they haven't paid me back,” then click Save & analyse statement.
4. Check the neutral AI summary, grounded facts, and 2–5 follow-up questions. Expanding a fact shows the exact supporting quote from the statement.
5. Answer every question, save, refresh, and confirm that the answers remain.
6. Edit the statement and save again. A new analysis should appear; the earlier intake remains in database history.
7. Temporarily use an invalid API key and confirm the page offers Retry analysis without losing the statement.
8. Use another account: it should neither list nor open the first account's matter or intake.
9. Upload a PDF, JPG, PNG, or WebP under 10 MB. It should first show Processing, then Processed with a factual extraction when Gemini is configured.
10. Open View and confirm the private file loads. Wait more than five minutes or sign out and confirm the old link cannot be used.
11. With GEMINI_API_KEY empty, upload another file. The upload remains safely stored and listed, while extraction shows a handled Failed state with a retry button.
12. Click Prepare facts for review. Values that agree should carry forward automatically; differing values should appear as a choice.
13. Resolve every mismatch, enter the recipient details, check the accuracy confirmation, and continue. The matter should become Ready for payment.
14. With Razorpay test credentials configured, click Pay securely with Razorpay and complete a test payment. Confirm the database and matter page move to Paid only after a valid payment.captured webhook.
15. After a paid matter produces a QA-approved draft, confirm it is assigned to an advocate and moves to Under advocate review. With no Gemini key, generation remains in its handled configuration state and does not crash either app.
16. Sign in as the seeded advocate. Confirm /advocate groups assigned work into pending, waiting for user, and completed queues.
17. Open an assignment and confirm the original statement, confirmed facts, private evidence links, QA result, and current draft are visible. Saving an edit should create a new advocate-authored version.

pnpm typecheck
pnpm test
pnpm build
# Isolated PostgreSQL + API integration checks (no live providers or existing databases):
node scripts/verify-integration.mjs
# Adversarial API + production website checks and 50/100-request read bursts:
node scripts/verify-integration.mjs --security
node scripts/security-static.mjs
# With API and database running: exercises real auth, persistence, and ownership.
node scripts/smoke.mjs
# With API + database running, exercises the successful answer path using a
# deterministic database fixture (no external AI call):
node --env-file=apps/api/.env scripts/phase2-success-smoke.mjs
# With API + database running, validates upload, private download, missing-key
# handling, retry, and cross-user isolation:
node scripts/phase3-smoke.mjs
# Start the API with the same temporary webhook secret, then run the deterministic
# reconciliation and webhook smoke test (no Gemini or Razorpay API call):
$env:RAZORPAY_WEBHOOK_SECRET='phase4-local-webhook-secret-at-least-32-characters'
node scripts/phase4-smoke.mjs

On Windows, stop the API before pnpm build or pnpm db:generate: its running process locks Prisma's engine DLL. Ordinary pnpm typecheck does not regenerate that DLL and can run while developing.

The smoke test creates two uniquely named test users and matters in the configured database and leaves those records for inspection. Only run it against a development/test database. It does not print passwords or tokens.

Structure and design decisions

• apps/web: Next.js App Router, TypeScript, Tailwind CSS. Server actions forward requests to Nest; the browser never receives the JWT in JavaScript. The JWT lives in a one-day HTTP-only, SameSite cookie (Secure in production). Protected server layouts validate it through /users/me, and every API operation independently checks the active account and session version. Logout revokes all sessions; staff password resets and account deactivation revoke old tokens too. State-changing website requests validate Origin against the configured APP_ORIGIN.
• apps/api: NestJS owns all business logic. Validation rejects unknown fields; auth endpoints are throttled; passwords use bcrypt with cost 12 and a 72-byte limit. Deploy behind HTTPS; throttling is in-memory for this single-instance foundation.
• apps/api/prisma: PostgreSQL schema and committed migrations. References use a database sequence, e.g. MAT-2026-000001, avoiding concurrent count-based collisions. The sequence is global, does not reset annually, and may have gaps after rollbacks.
• Statements are append-only snapshots; currentStatementId identifies the active version. Each analysis points to the exact statement and AI run that produced it, so an older response cannot replace a newer intake.
• Every Gemini attempt is recorded in ai_runs with provider, configured model, prompt version, statement reference, raw output when available, token usage, latency, status, and a sanitized error code. Matter work is claimed under PostgreSQL row locks, with five-minute leases for crash recovery. Each provider fallback chain has a two-minute client deadline; this leaves time for private file reads and commits before an attempt can be reclaimed.
• Gemini receives the statement only after save. Structured-output validation rejects malformed results, unknown fields, duplicate questions, and any extracted fact whose value and source quote cannot be found verbatim in the statement. The UI labels the result as AI-generated and asks the user to correct the source statement when needed.
• All matter and intake reads/writes filter by owner. Signup, login, matter creation, statement saves, intake requests, AI results, and answer saves create audit_logs records. No statement text, answer text, API key, or password is copied into audit logs.
• Evidence storage is behind a PrivateStorage abstraction. Local files use opaque server-generated keys outside static hosting. The API validates the declared MIME type, file signature, and size before storage, records a SHA-256 checksum, and never exposes the storage key.
• Evidence list results contain five-minute HMAC-signed view paths. Opening a file also requires the user's HTTP-only session and an ownership check. The Next.js route streams the authenticated API response without exposing the bearer token.

API_URL is server-only. No secrets use a NEXT_PUBLIC_ prefix. Only .env.example files are committed. The local servers bind to loopback by default. Production deployment templates are in deploy/vps; see the deployment guide for persistent storage, backups, HTTPS and hosting configuration. Rate limiting remains per API process.

Useful routes include POST /advocate/matters/:id/approve, GET /matters/:id/final-document, POST /matters/:id/final-document/retry, and GET /matters/:id/final-document/file.

For schema changes use pnpm --filter @lawmedy/api db:migrate:dev --name descriptive_name. Apply committed migrations using pnpm db:migrate.

Framework references: Next.js App Router, NestJS authentication, Prisma 6 migration history, and Razorpay Standard Checkout.