AWS guidance documentation change
Summary
Complete rewrite of the developer guide, transforming from a brief placeholder to a comprehensive guide covering source code, development environment setup, repository structure, CDK stacks, Flink application development, UI extension, API reference, testing, GSI/ISV integration, and best practices.
Security assessment
The change is a major content expansion, not a fix for a specific security vulnerability. However, it adds a new 'Security' subsection under 'Best practices' that provides general security guidance (least-privilege IAM, encryption, credential rotation, Secrets Manager, CloudTrail). This is proactive security documentation, not a response to an incident.
Diff
diff --git a/guidance/latest/connected-mobility-on-aws/developer-guide.md b/guidance/latest/connected-mobility-on-aws/developer-guide.md index 6242fd7ec..4706c3843 100644 --- a//guidance/latest/connected-mobility-on-aws/developer-guide.md +++ b//guidance/latest/connected-mobility-on-aws/developer-guide.md @@ -1 +1 @@ -[Documentation](/index.html)[Guidance for Connected Mobility on AWS](https://aws.amazon.com/solutions/guidance/connected-mobility-on-aws/)[Implementation Guide](guidance-overview.html) +[Documentation](/index.html)[Guidance for Connected Mobility on AWS](https://aws.amazon.com/solutions/guidance/connected-mobility-on-aws/)[Implementation Guide](solution-overview.html) @@ -3 +3 @@ -Customizing the guidanceAPI Reference +Source codeDevelopment environment setupRepository structureCDK stacksDeveloping Flink applicationsExtending Fleet Manager UIAPI referenceTesting and debuggingGSI and ISV integrationBest practices @@ -7 +7 @@ Customizing the guidanceAPI Reference -## Customizing the guidance +This section provides guidance for customizing and extending the Guidance for Connected Mobility on AWS using AWS CDK, developing Flink applications, extending the Fleet Manager UI, and integrating with external systems. @@ -9 +9 @@ Customizing the guidanceAPI Reference -### Adding New Vehicle Types +## Source code @@ -11 +11 @@ Customizing the guidanceAPI Reference - * Extend vehicle registration schemas in `modules/cms_ui/source/handlers/` +Visit our [GitHub repository](https://github.com/aws-solutions-library-samples/guidance-for-connected-mobility-on-aws) to download the source files for this solution and to share your customizations with others. @@ -13 +13 @@ Customizing the guidanceAPI Reference - * Update telemetry processing logic in `modules/flink/` +The solution uses [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/) for infrastructure as code. See the [README.md](https://github.com/aws-solutions-library-samples/guidance-for-connected-mobility-on-aws/blob/main/README.md) file for additional information. @@ -15 +15 @@ Customizing the guidanceAPI Reference - * Modify UI components in `modules/cms_ui/source/frontend/src/components/` +## Development environment setup @@ -16,0 +17 @@ Customizing the guidanceAPI Reference +### Prerequisites @@ -17,0 +19 @@ Customizing the guidanceAPI Reference + * AWS CLI v2 @@ -18,0 +21 @@ Customizing the guidanceAPI Reference + * Node.js 18.x or later @@ -20 +23 @@ Customizing the guidanceAPI Reference -### Custom Analytics + * Python 3.9 or later @@ -22 +25 @@ Customizing the guidanceAPI Reference - * Create new Flink processors for custom data analysis + * AWS CDK v2.100.0 or later @@ -24 +27 @@ Customizing the guidanceAPI Reference - * Add DynamoDB tables for new data types + * Git @@ -26 +29 @@ Customizing the guidanceAPI Reference - * Implement API endpoints for data access + * IDE (VS Code, PyCharm, or IntelliJ recommended) @@ -31 +34 @@ Customizing the guidanceAPI Reference -## API Reference +### Clone and setup @@ -33 +35,0 @@ Customizing the guidanceAPI Reference -The guidance provides REST APIs for: @@ -35 +37,3 @@ The guidance provides REST APIs for: - * Vehicle management and registration + # Clone repository + git clone https://github.com/aws-solutions-library-samples/guidance-for-connected-mobility-on-aws.git + cd guidance-for-connected-mobility-on-aws @@ -37 +41,3 @@ The guidance provides REST APIs for: - * Fleet operations and monitoring + # Install dependencies + cd deployment + make install @@ -39 +45,2 @@ The guidance provides REST APIs for: - * Telemetry data access and querying + # Activate virtual environment + source .venv/bin/activate @@ -41 +48,627 @@ The guidance provides REST APIs for: - * User management and authentication +## Repository structure + + + guidance-for-connected-mobility-on-aws/ + ├── deployment/ + │ ├── app.py # CDK application entry point + │ ├── stacks/ # CDK stack definitions + │ │ ├── commands_stack.py # Remote vehicle commands API + │ │ ├── data_processing_stack.py # Signal catalog and transform manifests + │ │ ├── fleetwise_stack.py # FleetWise Edge integration + │ │ ├── flink_stack.py # Flink stream processing applications + │ │ ├── infrastructure_stack.py # VPC, subnets, networking + │ │ ├── iot_stack.py # Fleet management IoT components + │ │ ├── msk_stack.py # MSK cluster, VPC, and ElastiCache + │ │ ├── oem_processor_stack.py # OEM telemetry ingestion + │ │ ├── predictive_agent_stack.py # Predictive maintenance AI agent + │ │ ├── simulation_stack.py # ECS Fargate vehicle simulator + │ │ ├── storage_stack.py # DynamoDB tables + │ │ ├── telemetry_integration_stack.py # MSK-IoT connectivity + │ │ └── ui_stack.py # Frontend, API Gateway, Cognito + │ ├── Makefile # Deployment automation + │ └── requirements.txt + ├── modules/ + │ ├── campaign_manager/ # FleetWise campaign management + │ ├── cms_ui/ # React frontend application + │ │ └── source/ + │ │ ├── frontend/ # React app (Cloudscape Design) + │ │ └── handlers/ # API Lambda handlers + │ ├── flink/ # Java Flink processors + │ └── oem_ingestion/ # OEM data ingestion consumer + ├── services/ + │ ├── commands/ # Remote commands Lambda + protobuf + │ ├── data_processing/ # Data processing service + │ └── simulation/ # Vehicle simulation service + ├── scripts/ # Utility scripts + └── tests/e2e/ # End-to-end tests + +## CDK stacks + +The solution is deployed as a set of modular CDK stacks defined in `deployment/app.py`. Each stack can be deployed independently based on your requirements. + +### Stack overview + +Stack | Purpose | Condition +---|---|--- +`DataProcessingStack` | Signal catalog and transform manifests | Always deployed +`StorageStack` | DynamoDB tables for vehicles, trips, telemetry, safety events, maintenance alerts, drivers, and more | Always deployed +`MSKStack` | VPC, Amazon MSK (Kafka) cluster, and ElastiCache for Redis | Deployed unless `MSK_CLUSTER_ARN` is provided +`IoTStack` | Fleet management IoT components | Always deployed +`TelemetryIntegrationStack` | MSK-IoT connectivity (IoT rules, VPC destinations) | `DEPLOY_TELEMETRY_INTEGRATION=true` +`FlinkStack` | Flink stream processing applications (trip detection, safety, maintenance, telemetry, FWE decode, campaign sync) | Always deployed +`FleetWiseStack` | FleetWise Edge IoT rules, VPC endpoints, CampaignSyncProcessor | `DEPLOY_FLEETWISE=true` +`UIStack` | React frontend (Cloudscape Design), API Gateway, Cognito authentication, Amazon Location Service | Always deployed +`CommandsStack` | Remote vehicle commands API via IoT Core MQTT, geofence management | Always deployed +`PredictiveAgentStack` | Predictive maintenance AI agent | `DEPLOY_PREDICTIVE_AGENT=true` +`SimulationStack` | ECS Fargate vehicle simulation service | `DEPLOY_SIMULATION=true` + +### Customizing stacks + +Stack definitions are in `deployment/stacks/`. Each stack is a Python class that extends `Stack`. + +#### Example: Modify MSK configuration + + + # In deployment/stacks/msk_stack.py + + class MSKStack(Stack): + def __init__(self, scope, id, **kwargs): + super().__init__(scope, id, **kwargs) + + # Modify broker instance type + self.cluster = msk.CfnCluster( + self, "MSKCluster", + cluster_name=f"cms-{stage}-cluster", + kafka_version="3.5.1", + number_of_broker_nodes=3, + broker_node_group_info=msk.CfnCluster.BrokerNodeGroupInfoProperty( + instance_type="kafka.m5.xlarge", # Changed from m5.large + storage_info=msk.CfnCluster.StorageInfoProperty( + ebs_storage_info=msk.CfnCluster.EBSStorageInfoProperty( + volume_size=200 # Increased from 100GB + ) + ), + ) + ) + +#### Example: Add a new stack + +To add a custom stack, create a new file in `deployment/stacks/` and register it in `deployment/app.py`: + + + # 1. Create deployment/stacks/custom_stack.py + from aws_cdk import Stack + from constructs import Construct + + class CustomStack(Stack): + def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None: + super().__init__(scope, construct_id, **kwargs) + # Add your resources here + + # 2. Add to deployment/app.py + from stacks.custom_stack import CustomStack + + custom_stack = CustomStack( + app, + f"{stack_prefix}-custom", + env=env, + description="Guidance for Connected Mobility (SO9618) - Custom" + ) + +## Developing Flink applications + +### Flink project structure + + + modules/flink/ + ├── pom.xml # Maven configuration (Flink 1.18.1) + ├── src/ + │ └── main/ + │ ├── java/ + │ │ └── com/cms/telemetry/ + │ │ ├── UniversalProcessor.java # Entry point, routes to processor + │ │ ├── SimulatorPreprocessor.java # Decodes gzip+base64 simulator telemetry + │ │ ├── TelemetryProcessor.java # Writes telemetry to DDB + │ │ ├── EventDrivenTelemetryProcessor.java # Routes to domain topics + Redis LKS + │ │ ├── FWTelemetryProcessor.java # Decodes FWE protobuf, maps CAN signals + │ │ ├── CampaignSyncProcessor.java # FWE checkin → campaign push via IoT MQTT + │ │ ├── GeofenceProcessor.java # Evaluates positions against geofences + │ │ ├── OEMTelemetryProcessor.java # Transforms OEM telemetry via S3 manifests + │ │ ├── KafkaConfig.java # Shared Kafka reconnect/keepalive config + │ │ ├── SignalCatalogLoader.java # Loads signal catalog to Redis + │ │ ├── TripProcessor.java # Stateful trip detection (v2) + │ │ ├── SafetyProcessor.java # Safety event detection + │ │ ├── MaintenanceProcessor.java # Maintenance alerts + │ │ ├── TireTelemetryTransformer.java # Tire signal normalization + │ │ ├── TelemetryData.java # Data model