1gigE

Worker-first local services infrastructure for India.

OTP identity, realtime dispatch, settlement controls, ledger-backed payouts, and portable worker credentials in one platform.

Overview

1gigE is a worker-first platform for local services in India across categories such as ride hailing, delivery, ambulance, and neighborhood assistance. The platform is designed around a simple principle:

workers should not be treated as disposable marketplace inventory.

That principle shapes the system in three ways:

• operationally, through realtime dispatch and role-aware workflows
• financially, through explicit payout controls and double-entry ledgering
• reputationally, through portable worker credentials and visible proof rails

This repository contains the current implementation of that platform across backend APIs, settlement and compliance flows, unified app surfaces, and deployment infrastructure.

Why It Matters

Most local-services platforms optimize demand capture first and worker integrity later. 1gigE inverts that sequence. The system is being built so that worker trust, payout correctness, operational traceability, and service reliability are core platform properties rather than afterthoughts.

That means the product is not just a booking app. It is also:

• a payout and reconciliation system
• a territory-aware operations system
• a worker identity and credential system
• a policy-constrained platform with explicit safety gates

Current Product Scope

The repository currently covers a meaningful live slice of the platform:

• OTP-based authentication and session flows
• consumer and worker booking lifecycle APIs
• realtime route and event infrastructure
• pricing, quote generation, and gig financial snapshots
• ratings and dispute handling
• settlement batches, payout execution, and reconciliation jobs
• payout guardrails for KYC, AML, welfare, and dispute conditions
• portable worker credential issuance flows
• a unified app workspace for mobile and web surfaces

Core Capabilities

Worker-first operations

• role-aware backend routes for nagrik, karmik, and sanchalak
• gig lifecycle checkpoints including OTP verification stages
• territory-aware access rules for operational and settlement actions

Financial correctness

• PostgreSQL-backed transaction state
• double-entry ledger groups and settlement clearing flows
• payout execution through Razorpay adapters and reconciliation jobs
• financial event recording and payout guard validation

Trust and portability

• worker credential persistence and issuance services
• Polygon Amoy proof rail for visible credential anchoring
• schema-backed credential documentation for verifier evolution

Platform hardening

• JWT rotation support
• token revocation service
• request throttling and security telemetry
• layer-separation validation in CI

Repository Structure

Main workspaces

• src/ — canonical backend API, jobs, models, migrations, services, and tests
• apps/unified-app/ — unified client app workspace
• contracts/ — blockchain contracts and credential-related chain artifacts

Important root files

• Dockerfile — production container build
• railway.json — deployment/runtime wiring
• wrangler.jsonc — Cloudflare Workers asset configuration
• SYSTEM-CONTRACT.md — system policy and governance framing
• CONTRIBUTING.md — contribution workflow

Architecture Snapshot

Backend

The backend is a Node.js and Express service with Sequelize-backed models, Postgres persistence, Redis-assisted throttling and coordination, and scheduled reconciliation jobs.

Representative backend domains include:

• auth and role switching
• gig lifecycle orchestration
• settlement and payout execution
• disputes and ratings
• worker credentials
• compliance, AML, welfare, and territory policy

App layer

The app workspace is designed to support a unified experience across worker and consumer flows. It is paired with the backend rather than treated as a disconnected frontend shell.

Settlement model

The financial path is built around explicit states rather than implicit balance mutations:

• gig financial snapshots define the commercial breakdown
• ledger groups record the economic movement
• settlement items and batches model payout processing
• payout attempts and reconciliation jobs model external transfer state

That structure is intentional. It creates a stronger base for audits, recovery, and production operations.

Local Development

Prerequisites

• Node.js 22.x
• PostgreSQL
• Redis

Install dependencies

npm install
npm --prefix src install
npm --prefix apps/unified-app install

Run the backend

cd src
npm start

Run the backend in dev mode

cd src
npm run dev

Run the unified app

cd apps/unified-app
npm start

Run tests

From the repo root:

npm test

Or directly from the backend workspace:

cd src
npm test -- --runInBand

Run migrations

cd src
npm run migrate

Check migration status:

cd src
npm run migrate:status

Deployment

The repository is set up for container-based deployment and production-style startup orchestration.

Useful entry points:

• Dockerfile
• railway.json
• docker-compose.prod.yml
• start.sh

Quality and Safety

This repository includes explicit operational and governance checks beyond ordinary unit testing.

Available checks

• backend tests via npm test
• commit and PR layer validation via npm run validate:layers
• branch and policy reconciliation scripts in the root scripts/ workflow
• payout reconciliation and refund reconciliation jobs in src/jobs/

Security posture highlights

• OTP secrets are hashed with keyed HMAC
• JWT rotation and revocation flows are implemented
• payout execution is gated through compliance checks
• sensitive route flows use role checks, territory checks, and throttling

Documentation

Key references:

• SYSTEM-CONTRACT.md
• LOGIC.md
• docs/worker-credential-api-v1.md
• docs/worker-credential-schema-v1.json
• docs/SECURITY_XSS.md
• docs/route-contracts.md
• docs/visible-economy-map.md

Credits and Development Model

1gigE is built through a hybrid human-plus-AI engineering workflow.

• Founder / Product Direction / System Ownership: Rajesh Premnath Soni (Nutrazz)
• AI-assisted engineering support: OpenAI ChatGPT, Anthropic Claude, and OpenAI Codex

AI tools are used as engineering collaborators for implementation support, review assistance, and systems reasoning. Final integration decisions, repository stewardship, and product responsibility remain with the project owner.

License

MIT