Technical & Commercial Reference

The repeat-service flywheel

Customers don’t care about the technology stack. They care about one thing: “Will this help me get more repeat service jobs and stop losing customers because we forgot to follow up?”

This is the cycle that matters for an AC, RO, appliance, pest-control, solar or maintenance company. Every service job the platform records automatically schedules the next service reminder and a post-service follow-up — building a self-replenishing pipeline of repeat revenue.

Technology stack

A modern, containerised stack: Java 21 + Spring Boot on the backend, Next.js 16 on the frontend, PostgreSQL with row-level security for hard tenant isolation, Redis for performance and RabbitMQ for asynchronous notifications and reminders.

System architecture

Deployment overview (Phase 1)

Request flow

Asynchronous notifications (RabbitMQ)

JSON via Jackson2JsonMessageConverter; poison-message dead-lettering is planned for Phase 2. Redis supports rate limiting, the JWT denylist and hot dashboard reads.

Reminder engine

Module boundaries (bounded contexts)

Security model

• Authentication: short-lived accessToken (15 min, JWT HS256) + long-lived refreshToken (7 days) stored hashed (SHA-256) in refresh_tokens with rotation and revocation; logout revokes.
• Passwords: bcrypt via Spring Security; password reset uses a single-use token valid 2 hours.
• Authorization (RBAC): OWNER (everything + billing/settings), MANAGER (customers, equipment, jobs, technicians, reminders), TECHNICIAN (assigned jobs, notes, own schedule).
• Anti-enumeration: forgot-password always returns the same response; verification tokens for email confirm.
• Rate limiting: Redis keys auth:login:<email>:<ip> (5 per 15 min) and auth:forgot:<email> (3 per hour) with in-memory fallback; excess returns 429.
• CSRF/CORS: Bearer-only auth (no cookies) so CSRF is disabled; CORS is permissive in dev, restricted in prod.
• Error contract: RFC-7807-style 401s via RestAuthenticationEntryPoint; typed errors via global exception handler.

Scalability roadmap

• Extract services — split into auth-service, notification-service, ai-service when load justifies it (monolith-by-module keeps costs low now).
• Kafka — replaces RabbitMQ for higher-volume eventing/replay; the exchange abstraction keeps producers unchanged.
• Kubernetes — Helm + HPA once the single EC2 host saturates; RLS remains the isolation boundary.
• S3 — customer documents & job photos via pre-signed URLs.
• Multi-region / read replicas — read-only replicas for reporting; tenant-aware routing remains the invariant.

Multi-tenancy & data isolation

Model: shared schema + tenant_id column. Every tenant-scoped table carries a tenant_id UUID and a composite (tenant_id, …) index. One PostgreSQL cluster serves all tenants — the most cost-efficient model for Phase 1 — while isolation is enforced at two independent layers.

Layer 1 — application context (per request)

• TenantFilter resolves the tenant at request entry — the X-Tenant-ID header, falling back to the authenticated user’s tenant — and stores it in TenantContext, a ThreadLocal<UUID>.
• TenantInterceptor hooks pre/post-controller and always clears the context after the request so async work must propagate the tenant explicitly (never implicitly across threads).

Layer 2 — database connection binding

• TenantAwareDataSource decorates the connection pool; every getConnection() returns a TenantAwareConnection.
• On acquisition (and prepare-statement/commit paths) the connection runs SET app.current_tenant = '<tenantId>' and resets it when returned to the pool.

Layer 3 — PostgreSQL row-level security (defense in depth)

Each tenant-scoped table is protected with ENABLE + FORCE ROW LEVEL SECURITY and a single policy:

-- applied to every tenant-scoped table (V14)
ALTER TABLE service_jobs ENABLE ROW LEVEL SECURITY;
ALTER TABLE service_jobs FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON service_jobs
  FOR ALL
  USING (tenant_id::text = current_setting('app.current_tenant', true))
  WITH CHECK (tenant_id::text = current_setting('app.current_tenant', true));

Why this design scales

• Moving to Kubernetes or Kafka later does not touch tenancy — RLS stays the isolation invariant.
• Multi-region read replicas for reporting keep tenant-aware routing intact.
• Trade-off: all tenants share one instance, so Phase-1 capacity planning should target the largest tenant; this is the known cost of the shared-schema model.

Product features

Status legend: Implemented shipped in V1, Partial core shipped / next milestone, Planned roadmap item built into the pricing model.

Recommended India pricing (V1 launch)

Positioning: “Never Miss a Service. Never Miss a Follow-up.” The Professional plan is the featured offer — the tier most customers should land on. Before finalising any price, the per-tenant infrastructure + WhatsApp/SMS + email + AI + support cost should be calculated to confirm gross margin at these price points.

What each plan includes

Annual billing — roughly 10–20% below monthly

Offer an early-adopter annual plan rather than permanently discounting the product.

Implementation fees & add-on pricing

One-time implementation / onboarding fees

Implementation is never free for business customers. Fees cover business configuration, user setup, service categories, reminder configuration, data import, initial training, WhatsApp/SMS/email configuration and basic customisation.

Add-ons (usage-based — never unlimited in base plans)

ServiceFlow Custom — separate software offering

Some companies won’t want SaaS at all; they will ask MageTech to customise ServiceFlow for their business. A dedicated “Custom Software” line protects SaaS pricing while capturing these deals.

Large enterprise implementations are quoted significantly higher based on scope. A one-time implementation / onboarding fee always applies.

International pricing (US / UK / UAE / Australia / Canada)

Do not simply convert ₹2,499 into dollars. A separate international price structure — adjusted by market and customer size — protects margin where willingness-to-pay is higher.