# aswina1636/floci architecture

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

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

## Overview

Floci is a local AWS emulator: users point AWS SDKs, the CLI, or infrastructure-as-code tools at its endpoint and receive AWS-compatible service behavior. The repository implements a broad set of AWS service domains, shared protocol and request infrastructure, configurable local state, lifecycle controls, and Docker-backed execution for services that need it. The README also documents a lazily started browser console sidecar. Source excerpts are limited, so service-to-storage and request-dispatch links are omitted where the evidence does not establish them.

Main entry points: [`src/main/java/io/github/hectorvent/floci/core/common`](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/common) (AWS protocols), [`src/main/java/io/github/hectorvent/floci`](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci) (Local endpoint), [`src/main/java/io/github/hectorvent/floci/core/common/docker`](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/common/docker) (Docker runtime), [`src/main/java/io/github/hectorvent/floci/lifecycle/UiController.java`](https://github.com/aswina1636/floci/blob/main/src/main/java/io/github/hectorvent/floci/lifecycle/UiController.java) (Console controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared runtime"]
  node_endpoint["Local endpoint"]
  node_protocol["AWS protocols"]
  node_region["Request context"]
  node_config["Emulator config"]
  node_storage[("Local state")]
  node_lifecycle["Lifecycle and health"]
  node_iam["IAM and STS"]
end

subgraph group_compute["Compute and network"]
  node_ec2["EC2 networking"]
  node_lambda["Lambda execution"]
  node_ecs["ECS containers"]
  node_docker["Docker runtime"]
end

subgraph group_data["Data services"]
  node_rds["RDS databases"]
  node_docdb["DocumentDB"]
  node_dynamodb["DynamoDB"]
  node_s3["S3 storage"]
end

subgraph group_integration["Integration services"]
  node_sqs["SQS messaging"]
  node_sns["SNS messaging"]
  node_apigateway["API Gateway"]
  node_other_services["Other AWS services"]
end

subgraph group_console["Console"]
  node_ui_controller["Console controller<br/>[UiController.java]"]
  node_ui_sidecar["Console sidecar"]
end

node_aws_users(("AWS clients"))
node_browser(("Browser user"))

node_aws_users -->|"send AWS requests"| node_endpoint
node_endpoint -.->|"serve AWS APIs"| node_protocol
node_protocol -.->|"dispatches requests"| node_ec2
node_protocol -.->|"dispatches requests"| node_rds
node_protocol -.->|"dispatches requests"| node_docdb
node_protocol -.->|"dispatches requests"| node_dynamodb
node_protocol -.->|"dispatches requests"| node_s3
node_protocol -.->|"dispatches requests"| node_sqs
node_protocol -.->|"dispatches requests"| node_sns
node_protocol -.->|"dispatches requests"| node_lambda
node_protocol -.->|"dispatches requests"| node_ecs
node_protocol -.->|"dispatches requests"| node_apigateway
node_protocol -.->|"dispatches requests"| node_iam
node_protocol -.->|"dispatches requests"| node_other_services
node_config -.->|"configures runtime"| node_endpoint
node_browser -->|"opens console"| node_ui_controller
node_ui_controller -->|"starts sidecar"| node_ui_sidecar
node_ui_sidecar -->|"connects to Floci"| node_endpoint
node_ui_controller -->|"starts container"| node_docker
node_lifecycle -.->|"reports health"| node_endpoint
node_lambda -->|"runs in containers"| node_docker
node_rds -->|"runs in containers"| node_docker
node_ecs -->|"runs in containers"| node_docker

click node_endpoint "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci"
click node_protocol "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/common"
click node_region "https://github.com/aswina1636/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/RegionResolver.java"
click node_config "https://github.com/aswina1636/floci/blob/main/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java"
click node_storage "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/storage"
click node_lifecycle "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/lifecycle"
click node_ec2 "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/ec2"
click node_rds "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/rds"
click node_docdb "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/docdb"
click node_dynamodb "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/dynamodb"
click node_s3 "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/s3"
click node_sqs "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/sqs"
click node_sns "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/sns"
click node_lambda "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/lambda"
click node_ecs "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/ecs"
click node_apigateway "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/apigateway"
click node_iam "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/iam"
click node_other_services "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services"
click node_docker "https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/common/docker"
click node_ui_controller "https://github.com/aswina1636/floci/blob/main/src/main/java/io/github/hectorvent/floci/lifecycle/UiController.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_protocol,node_region,node_config,node_storage,node_lifecycle,node_iam,node_aws_users,node_browser toneBlue
class node_ec2,node_lambda,node_ecs,node_docker toneAmber
class node_rds,node_docdb,node_dynamodb,node_s3 toneMint
class node_sqs,node_sns,node_apigateway,node_other_services toneRose
class node_ui_controller,node_ui_sidecar toneIndigo
```

## Components

### Shared runtime

- [Local endpoint](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci): `src/main/java/io/github/hectorvent/floci`
- [AWS protocols](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/common): `src/main/java/io/github/hectorvent/floci/core/common`
- [Request context](https://github.com/aswina1636/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/RegionResolver.java): `src/main/java/io/github/hectorvent/floci/core/common/RegionResolver.java`
- [Emulator config](https://github.com/aswina1636/floci/blob/main/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java): `src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java`
- [Local state](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/storage): `src/main/java/io/github/hectorvent/floci/core/storage`
- [Lifecycle and health](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/lifecycle): `src/main/java/io/github/hectorvent/floci/lifecycle`
- [IAM and STS](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/iam): `src/main/java/io/github/hectorvent/floci/services/iam`

### Compute and network

- [EC2 networking](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/ec2): `src/main/java/io/github/hectorvent/floci/services/ec2`
- [Lambda execution](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/lambda): `src/main/java/io/github/hectorvent/floci/services/lambda`
- [ECS containers](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/ecs): `src/main/java/io/github/hectorvent/floci/services/ecs`
- [Docker runtime](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/core/common/docker): `src/main/java/io/github/hectorvent/floci/core/common/docker`

### Data services

- [RDS databases](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/rds): `src/main/java/io/github/hectorvent/floci/services/rds`
- [DocumentDB](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/docdb): `src/main/java/io/github/hectorvent/floci/services/docdb`
- [DynamoDB](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/dynamodb): `src/main/java/io/github/hectorvent/floci/services/dynamodb`
- [S3 storage](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/s3): `src/main/java/io/github/hectorvent/floci/services/s3`

### Integration services

- [SQS messaging](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/sqs): `src/main/java/io/github/hectorvent/floci/services/sqs`
- [SNS messaging](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/sns): `src/main/java/io/github/hectorvent/floci/services/sns`
- [API Gateway](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services/apigateway): `src/main/java/io/github/hectorvent/floci/services/apigateway`
- [Other AWS services](https://github.com/aswina1636/floci/tree/main/src/main/java/io/github/hectorvent/floci/services): `src/main/java/io/github/hectorvent/floci/services`

### Console

- [Console controller](https://github.com/aswina1636/floci/blob/main/src/main/java/io/github/hectorvent/floci/lifecycle/UiController.java): `src/main/java/io/github/hectorvent/floci/lifecycle/UiController.java`
- **Console sidecar**

### Other components

- **AWS clients**
- **Browser user**

## Connections

- AWS clients → Local endpoint: send AWS requests (evidence: `README.md`)
- Local endpoint → AWS protocols: serve AWS APIs (evidence: `src/main/java/io/github/hectorvent/floci/services/codepipeline/CodePipelineService.java`)
- AWS protocols → EC2 networking: dispatches requests (evidence: `src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java`)
- AWS protocols → RDS databases: dispatches requests (evidence: `src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java`)
- AWS protocols → DocumentDB: dispatches requests (evidence: `src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java`)
- AWS protocols → DynamoDB: dispatches requests
- AWS protocols → S3 storage: dispatches requests
- AWS protocols → SQS messaging: dispatches requests (evidence: `src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java`)
- AWS protocols → SNS messaging: dispatches requests (evidence: `src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java`)
- AWS protocols → Lambda execution: dispatches requests
- AWS protocols → ECS containers: dispatches requests
- AWS protocols → API Gateway: dispatches requests
- AWS protocols → IAM and STS: dispatches requests (evidence: `src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java`)
- AWS protocols → Other AWS services: dispatches requests (evidence: `src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java`)
- Emulator config → Local endpoint: configures runtime (evidence: `src/main/java/io/github/hectorvent/floci/services/codepipeline/CodePipelineService.java`)
- Browser user → Console controller: opens console (evidence: `README.md`)
- Console controller → Console sidecar: starts sidecar (evidence: `README.md`)
- Console sidecar → Local endpoint: connects to Floci (evidence: `README.md`)
- Console controller → Docker runtime: starts container (evidence: `README.md`)
- Lifecycle and health → Local endpoint: reports health
- Lambda execution → Docker runtime: runs in containers (evidence: `README.md`)
- RDS databases → Docker runtime: runs in containers (evidence: `README.md`)
- ECS containers → Docker runtime: runs in containers (evidence: `README.md`)
