#5 add initial serverless project

Author: jayhill

serverless/README.md

@@ -0,0 +1,68 @@
+# Detention Data API
+
+This is the backend API for the Detention Data project, built with the Serverless Framework and AWS services.
+
+## Architecture
+
+-   **AWS Lambda**: Serverless functions for API endpoints and scheduled data collection
+-   **Amazon DynamoDB**: NoSQL database for storing detention data
+-   **Amazon API Gateway**: REST API with API key authentication
+-   **AWS EventBridge**: Scheduled triggers for data collection
+-   **AWS CloudWatch**: Logging and monitoring
+
+## Project Structure
+
+```
+serverless/
+├── api/                    # API service
+│   ├── handlers/          # Lambda function handlers
+│   │   ├── data-collection.ts    # Scheduled data collection
+│   │   ├── detainee.ts           # Detainee CRUD operations
+│   │   └── status.ts             # Health check endpoint
+│   └── serverless.yml     # Serverless configuration
+├── package.json           # Dependencies and scripts
+├── tsconfig.json          # TypeScript configuration
+└── eslint.config.js       # ESLint configuration
+```
+
+## API Endpoints
+
+-   `GET /status` - Health check
+-   `GET /detainee/{detaineeId}` - Get detainee records
+-   `GET /detainees/active` - List active detainees
+
+## Scheduled Functions
+
+-   **Data Collection**: Runs daily at 10 AM UTC to collect detention data from configured county sources
+
+## Development
+
+1. Install dependencies:
+
+    ```bash
+    npm install
+    ```
+
+2. Deploy to dev environment:
+
+    ```bash
+    npx serverless deploy --stage dev
+    ```
+
+3. Run tests:
+    ```bash
+    npm test
+    ```
+
+## Configuration
+
+The scheduled data collection can be configured by adding additional schedule events in `serverless.yml`:
+
+```yaml
+functions:
+    dataCollection:
+        events:
+            - schedule:
+                  rate: cron(30 10 * * ? *)
+                  input: '{"countyId": "mecklenburg", "source": "mecklenburg-county"}'
+```

serverless/api/handlers/data-collection.ts

@@ -0,0 +1,141 @@
+import {
+  APIGatewayProxyEvent,
+  APIGatewayProxyResult,
+  ScheduledEvent,
+} from "aws-lambda";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
+
+const dynamoClient = new DynamoDBClient({ region: process.env.AWS_REGION });
+const docClient = DynamoDBDocumentClient.from(dynamoClient);
+
+interface JailDataEvent {
+  countyId: string;
+  source: string;
+}
+
+interface DetentionRecord {
+  detaineeId: string;
+  timestamp: string;
+  status: "ACTIVE" | "INACTIVE";
+  createdDate: string;
+  countyId: string;
+  source: string;
+  // Add other fields as needed
+  firstName?: string;
+  lastName?: string;
+  bookingDate?: string;
+  charges?: string[];
+  ttl?: number;
+}
+
+export const execute = async (
+  event: ScheduledEvent | APIGatewayProxyEvent
+): Promise<APIGatewayProxyResult | void> => {
+  try {
+    console.log("Data collection started", JSON.stringify(event, null, 2));
+
+    // Parse input from scheduled event or API Gateway
+    let inputData: JailDataEvent;
+
+    if ("source" in event && event.source === "aws.events") {
+      // Scheduled event
+      const scheduledEvent = event as ScheduledEvent;
+      inputData = JSON.parse(
+        scheduledEvent.detail ? JSON.stringify(scheduledEvent.detail) : "{}"
+      );
+    } else {
+      // API Gateway event (for manual testing)
+      const apiEvent = event as APIGatewayProxyEvent;
+      inputData = JSON.parse(apiEvent.body || "{}");
+    }
+
+    const { countyId, source } = inputData;
+
+    if (!countyId || !source) {
+      const error = "Missing required parameters: countyId and source";
+      console.error(error);
+
+      if ("httpMethod" in event) {
+        return {
+          statusCode: 400,
+          body: JSON.stringify({ error }),
+        };
+      }
+      return;
+    }
+
+    // TODO: Implement actual data collection logic
+    // This is a stub that would be replaced with real county data scraping
+    const mockData = await collectJailData(countyId, source);
+
+    // Store the collected data
+    const results = await Promise.all(
+      mockData.map((record) => storeDetentionRecord(record))
+    );
+
+    console.log(
+      `Successfully processed ${results.length} records for ${countyId}`
+    );
+
+    if ("httpMethod" in event) {
+      return {
+        statusCode: 200,
+        body: JSON.stringify({
+          message: `Successfully processed ${results.length} records`,
+          countyId,
+          source,
+        }),
+      };
+    }
+  } catch (error) {
+    console.error("Error in data collection:", error);
+
+    if ("httpMethod" in event) {
+      return {
+        statusCode: 500,
+        body: JSON.stringify({ error: "Internal server error" }),
+      };
+    }
+    throw error;
+  }
+};
+
+async function collectJailData(
+  countyId: string,
+  source: string
+): Promise<DetentionRecord[]> {
+  // This is a stub - replace with actual data collection logic
+  console.log(`Collecting data for county: ${countyId}, source: ${source}`);
+
+  // Mock data for demonstration
+  const now = new Date();
+  const today = now.toISOString().split("T")[0];
+  const timestamp = now.toISOString();
+
+  return [
+    {
+      detaineeId: `${countyId}-${Date.now()}-001`,
+      timestamp,
+      status: "ACTIVE",
+      createdDate: today,
+      countyId,
+      source,
+      firstName: "John",
+      lastName: "Doe",
+      bookingDate: today,
+      charges: ["DWI", "Traffic Violation"],
+      ttl: Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60, // 1 year TTL
+    },
+  ];
+}
+
+async function storeDetentionRecord(record: DetentionRecord): Promise<void> {
+  const params = {
+    TableName: process.env.JAILDATA_TABLE!,
+    Item: record,
+  };
+
+  await docClient.send(new PutCommand(params));
+  console.log(`Stored record for detainee: ${record.detaineeId}`);
+}

serverless/api/handlers/detainee.ts

@@ -0,0 +1,114 @@
+import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import {
+  DynamoDBDocumentClient,
+  GetCommand,
+  QueryCommand,
+} from "@aws-sdk/lib-dynamodb";
+
+const dynamoClient = new DynamoDBClient({ region: process.env.AWS_REGION });
+const docClient = DynamoDBDocumentClient.from(dynamoClient);
+
+export const get = async (
+  event: APIGatewayProxyEvent
+): Promise<APIGatewayProxyResult> => {
+  try {
+    const detaineeId = event.pathParameters?.detaineeId;
+
+    if (!detaineeId) {
+      return {
+        statusCode: 400,
+        body: JSON.stringify({ error: "Missing detaineeId parameter" }),
+      };
+    }
+
+    const params = {
+      TableName: process.env.JAILDATA_TABLE!,
+      KeyConditionExpression: "detaineeId = :detaineeId",
+      ExpressionAttributeValues: {
+        ":detaineeId": detaineeId,
+      },
+      ScanIndexForward: false, // Most recent first
+      Limit: 10, // Get last 10 records
+    };
+
+    const result = await docClient.send(new QueryCommand(params));
+
+    if (!result.Items || result.Items.length === 0) {
+      return {
+        statusCode: 404,
+        body: JSON.stringify({ error: "Detainee not found" }),
+      };
+    }
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify({
+        detaineeId,
+        records: result.Items,
+        count: result.Items.length,
+      }),
+    };
+  } catch (error) {
+    console.error("Error getting detainee:", error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: "Internal server error" }),
+    };
+  }
+};
+
+export const listActive = async (
+  event: APIGatewayProxyEvent
+): Promise<APIGatewayProxyResult> => {
+  try {
+    const limit = event.queryStringParameters?.limit
+      ? parseInt(event.queryStringParameters.limit)
+      : 100;
+    const daysBack = event.queryStringParameters?.days
+      ? parseInt(event.queryStringParameters.days)
+      : 7;
+
+    // Calculate date range
+    const endDate = new Date();
+    const startDate = new Date(
+      endDate.getTime() - daysBack * 24 * 60 * 60 * 1000
+    );
+    const startDateStr = startDate.toISOString().split("T")[0];
+
+    const params = {
+      TableName: process.env.JAILDATA_TABLE!,
+      IndexName: "StatusCreatedDateIndex",
+      KeyConditionExpression: "#status = :status AND createdDate >= :startDate",
+      ExpressionAttributeNames: {
+        "#status": "status",
+      },
+      ExpressionAttributeValues: {
+        ":status": "ACTIVE",
+        ":startDate": startDateStr,
+      },
+      ScanIndexForward: false, // Most recent first
+      Limit: limit,
+    };
+
+    const result = await docClient.send(new QueryCommand(params));
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify({
+        activeDetainees: result.Items || [],
+        count: result.Items?.length || 0,
+        dateRange: {
+          start: startDateStr,
+          end: endDate.toISOString().split("T")[0],
+        },
+      }),
+    };
+  } catch (error) {
+    console.error("Error listing active detainees:", error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: "Internal server error" }),
+    };
+  }
+};

serverless/api/handlers/status.ts

@@ -0,0 +1,32 @@
+import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+
+export const get = async (
+  event: APIGatewayProxyEvent
+): Promise<APIGatewayProxyResult> => {
+  try {
+    // Basic health check
+    const status = {
+      service: "detention-data-api",
+      status: "healthy",
+      timestamp: new Date().toISOString(),
+      environment: process.env.STAGE || "unknown",
+      version: "1.0.0",
+    };
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify(status),
+    };
+  } catch (error) {
+    console.error("Error in status check:", error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({
+        service: "jaildata-api",
+        status: "unhealthy",
+        error: "Internal server error",
+        timestamp: new Date().toISOString(),
+      }),
+    };
+  }
+};