Rechargematch: Building a Physics-Aware Urban Groundwater Recharge Engine on Serverless AWS

Elevation(Site) <= Elevation(Hotspot) + 0.3 m


1. Upstream sheet runoff     : V_runoff = C × P × A
2. Physical tank storage     : V_store  = L × W × D × void_ratio
3. 48-hour soil percolation  : V_drain  = f × A_floor × 48 hours
4. Structure design capacity : V_design = min(V_store, V_drain)
5. Ward absorption gap       : V_gap    = V_runoff - Σ V_captured


┌────────────────────────────────────┐
│   RechargeMatch Web Planner        │
│ (React 19 + TypeScript + GisMap)   │
└─────────┬──────────────────┬───────┘
          │ 1. REST JSON     │ 3. Direct PUT (Pre-Signed URL)
          ▼                  │
┌─────────────────────────┐  │
│   Amazon API Gateway    │  │
│     (HTTP API v2)       │  │
└─────────┬───────────────┘  │
          │ 2. Invoke        │
          ▼                  ▼
┌─────────────────────────┐ ┌──────────────────────────────┐
│       AWS Lambda        │ │          Amazon S3           │
│ (Node.js 20.x Handler)  │ │ (Sanitized Evidence Bucket)  │
└─────────┬───────────────┘ └──────────────────────────────┘
          │ 4. PutCommand / QueryCommand
          ▼
┌─────────────────────────┐
│     Amazon DynamoDB     │
│ (On-Demand Ward Table)  │
└─────────────────────────┘


import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand, QueryCommand } from "@aws-sdk/lib-dynamodb";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const region = process.env.AWS_REGION || "ap-southeast-2";
const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({ region }));
const s3 = new S3Client({ region });

const TABLE_NAME = process.env.DDB_TABLE;
const BUCKET_NAME = process.env.S3_BUCKET;

export const handler = async (event) => {
  const method = event.requestContext?.http?.method || "GET";
  const path = event.rawPath || "/";

  // 1. Ingest a geotagged citizen waterlogging report into DynamoDB
  if (method === "POST" && path.endsWith("/reports")) {
    const report = JSON.parse(event.body || "{}");
    const item = {
      wardId: report.wardId || "ward-142",
      id: report.id || `rep-${Date.now()}`,
      ...report,
      createdAt: new Date().toISOString()
    };

    await ddb.send(new PutCommand({ TableName: TABLE_NAME, Item: item }));
    return { statusCode: 201, body: JSON.stringify({ synced: true, id: item.id }) };
  }

  // 2. Generate a 5-minute S3 pre-signed URL for field photos
  if (method === "POST" && path.endsWith("/uploads/presign")) {
    const { fileName, contentType } = JSON.parse(event.body || "{}");
    const key = `reports/${Date.now()}-${(fileName || "photo.jpg").replace(/[^a-zA-Z0-9._-]/g, "_")}`;

    const command = new PutObjectCommand({
      Bucket: BUCKET_NAME,
      Key: key,
      ContentType: contentType || "image/jpeg"
    });

    const uploadUrl = await getSignedUrl(s3, command, { expiresIn: 300 });
    const publicFileUrl = `https://${BUCKET_NAME}.s3.${region}.amazonaws.com/${key}`;
    return { statusCode: 200, body: JSON.stringify({ uploadUrl, publicFileUrl }) };
  }

  // 3. Fetch ward telemetry from DynamoDB
  if (method === "GET" && path.includes("/wards/")) {
    const wardId = path.split("/").pop() || "ward-142";
    const result = await ddb.send(
      new QueryCommand({
        TableName: TABLE_NAME,
        KeyConditionExpression: "wardId = :w",
        ExpressionAttributeValues: { ":w": wardId }
      })
    );
    return { statusCode: 200, body: JSON.stringify({ wardId, reports: result.Items || [] }) };
  }
};