# floci-io/floci architecture

> Architecture diagram of the GitHub repository floci-io/floci, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/floci-io/floci
- Repository: https://github.com/floci-io/floci

## Overview

Floci is a local AWS emulator: users direct standard AWS clients to its local endpoint, issue AWS-shaped requests, and receive compatible responses. The repository includes protocol and service implementations, persistent storage, lifecycle management, configuration, and a Docker-backed web-console sidecar. The README documents the client and console workflows; sampled source and the SOURCE INDEX support selected service-to-core relationships. Many service implementations and runtime routes were not sampled, so those internal links are omitted.

Main entry points: [`src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java) (EC2 API), [`src/main/java/io/floci/aws/core/common`](https://github.com/floci-io/floci/tree/main/src/main/java/io/floci/aws/core/common) (Local Endpoint), [`src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java`](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java) (RDS API), [`src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java`](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java) (Auto Scaling API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Request Runtime"]
  node_endpoint["Local Endpoint"]
  node_region["Region Resolver"]
  node_arn["ARN Utilities<br/>[AwsArnUtils.java]"]
  node_queryresponse["Query Responses"]
  node_xml["XML Builder<br/>[XmlBuilder.java]"]
  node_errors["AWS Errors<br/>[AwsException.java]"]
  node_pagination["Pagination<br/>[Pagination.java]"]
  node_namespaces["AWS Namespaces<br/>[AwsNamespaces.java]"]
end

subgraph group_services["AWS Services"]
  node_ec2["EC2 API"]
  node_ec2service["EC2 Service<br/>[Ec2Service.java]"]
  node_rds["RDS API"]
  node_rdsservice["RDS Service<br/>[RdsService.java]"]
  node_iam["IAM API"]
  node_autoscaling["Auto Scaling API"]
  node_pipeline["CodePipeline"]
end

subgraph group_state["State and Storage"]
  node_storagefactory["Storage Factory"]
  node_storagebackend["Storage Backend"]
  node_accountstorage["Account Storage"]
end

subgraph group_operations["Lifecycle and Integrations"]
  node_lifecycle["Emulator Lifecycle"]
  node_ui["Console Controller<br/>[UiController.java]"]
  node_sidecar["Console Sidecar"]
  node_docker["Docker Runtime"]
  node_config["Emulator Config"]
end

node_client(("AWS Client"))

node_client -->|"sends requests"| node_endpoint
node_ec2 -->|"calls"| node_ec2service
node_rds -->|"calls"| node_rdsservice
node_ec2 -->|"uses"| node_region
node_ec2 -->|"uses"| node_arn
node_ec2 -->|"uses"| node_errors
node_ec2 -->|"builds XML"| node_xml
node_ec2 -->|"uses"| node_namespaces
node_ec2 -->|"uses"| node_pagination
node_rds -->|"uses"| node_errors
node_rds -->|"builds XML"| node_xml
node_rds -->|"uses"| node_namespaces
node_rds -->|"uses"| node_pagination
node_iam -->|"uses"| node_region
node_iam -->|"uses"| node_pagination
node_autoscaling -->|"uses"| node_errors
node_autoscaling -->|"builds XML"| node_xml
node_autoscaling -->|"uses"| node_pagination
node_pipeline -->|"uses"| node_storagebackend
node_pipeline -->|"uses"| node_accountstorage
node_storagefactory -.->|"creates"| node_storagebackend
node_endpoint -.->|"routes to"| node_ec2
node_endpoint -.->|"routes to"| node_rds
node_endpoint -.->|"routes to"| node_iam
node_endpoint -.->|"routes to"| node_autoscaling
node_endpoint -->|"serves console"| node_ui
node_ui -->|"starts and checks"| node_sidecar
node_ui -->|"uses Docker"| node_docker
node_lifecycle -.->|"uses configuration"| node_config

click node_endpoint "https://github.com/floci-io/floci/tree/main/src/main/java/io/floci/aws/core/common"
click node_region "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/RegionResolver.java"
click node_arn "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsArnUtils.java"
click node_queryresponse "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsQueryResponse.java"
click node_xml "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/XmlBuilder.java"
click node_errors "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsException.java"
click node_pagination "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/Pagination.java"
click node_namespaces "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsNamespaces.java"
click node_ec2 "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java"
click node_ec2service "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/ec2/Ec2Service.java"
click node_rds "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java"
click node_rdsservice "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/rds/RdsService.java"
click node_iam "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/iam/IamQueryHandler.java"
click node_autoscaling "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java"
click node_pipeline "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/codepipeline/CodePipelineService.java"
click node_storagefactory "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/storage/StorageFactory.java"
click node_storagebackend "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/storage/StorageBackend.java"
click node_accountstorage "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/storage/AccountAwareStorageBackend.java"
click node_lifecycle "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/lifecycle/EmulatorLifecycle.java"
click node_ui "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/lifecycle/UiController.java"
click node_docker "https://github.com/floci-io/floci/tree/main/src/main/java/io/floci/aws/core/common/docker"
click node_config "https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/config/EmulatorConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_endpoint,node_region,node_arn,node_queryresponse,node_xml,node_errors,node_pagination,node_namespaces,node_client toneBlue
class node_ec2,node_ec2service,node_rds,node_rdsservice,node_iam,node_autoscaling,node_pipeline toneAmber
class node_storagefactory,node_storagebackend,node_accountstorage toneMint
class node_lifecycle,node_ui,node_sidecar,node_docker,node_config toneRose
```

## Components

### Request Runtime

- [Local Endpoint](https://github.com/floci-io/floci/tree/main/src/main/java/io/floci/aws/core/common): `src/main/java/io/floci/aws/core/common`
- [Region Resolver](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/RegionResolver.java): `src/main/java/io/floci/aws/core/common/RegionResolver.java`
- [ARN Utilities](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsArnUtils.java): `src/main/java/io/floci/aws/core/common/AwsArnUtils.java`
- [Query Responses](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsQueryResponse.java): `src/main/java/io/floci/aws/core/common/AwsQueryResponse.java`
- [XML Builder](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/XmlBuilder.java): `src/main/java/io/floci/aws/core/common/XmlBuilder.java`
- [AWS Errors](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsException.java): `src/main/java/io/floci/aws/core/common/AwsException.java`
- [Pagination](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/Pagination.java): `src/main/java/io/floci/aws/core/common/Pagination.java`
- [AWS Namespaces](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/common/AwsNamespaces.java): `src/main/java/io/floci/aws/core/common/AwsNamespaces.java`

### AWS Services

- [EC2 API](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java): `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`
- [EC2 Service](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/ec2/Ec2Service.java): `src/main/java/io/floci/aws/services/ec2/Ec2Service.java`
- [RDS API](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java): `src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java`
- [RDS Service](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/rds/RdsService.java): `src/main/java/io/floci/aws/services/rds/RdsService.java`
- [IAM API](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/iam/IamQueryHandler.java): `src/main/java/io/floci/aws/services/iam/IamQueryHandler.java`
- [Auto Scaling API](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java): `src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java`
- [CodePipeline](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/services/codepipeline/CodePipelineService.java): `src/main/java/io/floci/aws/services/codepipeline/CodePipelineService.java`

### State and Storage

- [Storage Factory](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/storage/StorageFactory.java): `src/main/java/io/floci/aws/core/storage/StorageFactory.java`
- [Storage Backend](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/storage/StorageBackend.java): `src/main/java/io/floci/aws/core/storage/StorageBackend.java`
- [Account Storage](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/core/storage/AccountAwareStorageBackend.java): `src/main/java/io/floci/aws/core/storage/AccountAwareStorageBackend.java`

### Lifecycle and Integrations

- [Emulator Lifecycle](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/lifecycle/EmulatorLifecycle.java): `src/main/java/io/floci/aws/lifecycle/EmulatorLifecycle.java`
- [Console Controller](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/lifecycle/UiController.java): `src/main/java/io/floci/aws/lifecycle/UiController.java`
- **Console Sidecar**
- [Docker Runtime](https://github.com/floci-io/floci/tree/main/src/main/java/io/floci/aws/core/common/docker): `src/main/java/io/floci/aws/core/common/docker`
- [Emulator Config](https://github.com/floci-io/floci/blob/main/src/main/java/io/floci/aws/config/EmulatorConfig.java): `src/main/java/io/floci/aws/config/EmulatorConfig.java`

### Other components

- **AWS Client**

## Connections

- AWS Client → Local Endpoint: sends requests
- EC2 API → EC2 Service: calls (evidence: `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`)
- RDS API → RDS Service: calls (evidence: `src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java`)
- EC2 API → Region Resolver: uses (evidence: `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`)
- EC2 API → ARN Utilities: uses (evidence: `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`)
- EC2 API → AWS Errors: uses (evidence: `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`)
- EC2 API → XML Builder: builds XML (evidence: `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`)
- EC2 API → AWS Namespaces: uses (evidence: `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`)
- EC2 API → Pagination: uses (evidence: `src/main/java/io/floci/aws/services/ec2/Ec2QueryHandler.java`)
- RDS API → AWS Errors: uses (evidence: `src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java`)
- RDS API → XML Builder: builds XML (evidence: `src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java`)
- RDS API → AWS Namespaces: uses (evidence: `src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java`)
- RDS API → Pagination: uses (evidence: `src/main/java/io/floci/aws/services/rds/RdsQueryHandler.java`)
- IAM API → Region Resolver: uses (evidence: `src/main/java/io/floci/aws/services/iam/IamQueryHandler.java`)
- IAM API → Pagination: uses (evidence: `src/main/java/io/floci/aws/services/iam/IamQueryHandler.java`)
- Auto Scaling API → AWS Errors: uses (evidence: `src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java`)
- Auto Scaling API → XML Builder: builds XML (evidence: `src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java`)
- Auto Scaling API → Pagination: uses (evidence: `src/main/java/io/floci/aws/services/autoscaling/AutoScalingQueryHandler.java`)
- CodePipeline → Storage Backend: uses (evidence: `src/main/java/io/floci/aws/services/codepipeline/CodePipelineService.java`)
- CodePipeline → Account Storage: uses (evidence: `src/main/java/io/floci/aws/services/codepipeline/CodePipelineService.java`)
- Storage Factory → Storage Backend: creates (evidence: `src/main/java/io/floci/aws/core/storage/StorageFactory.java`)
- Local Endpoint → EC2 API: routes to (evidence: `src/main/java/io/floci/aws/core/common/AwsQueryController.java`)
- Local Endpoint → RDS API: routes to (evidence: `src/main/java/io/floci/aws/core/common/AwsQueryController.java`)
- Local Endpoint → IAM API: routes to (evidence: `src/main/java/io/floci/aws/core/common/AwsQueryController.java`)
- Local Endpoint → Auto Scaling API: routes to (evidence: `src/main/java/io/floci/aws/core/common/AwsQueryController.java`)
- Local Endpoint → Console Controller: serves console
- Console Controller → Console Sidecar: starts and checks
- Console Controller → Docker Runtime: uses Docker
- Emulator Lifecycle → Emulator Config: uses configuration
