Building Blocks
Chinilla uses 7 universal building blocks. They work for any domain: software, restaurants, hospitals, factories, logistics. No infrastructure jargon required.
The 7 blocks
Section titled “The 7 blocks”| Block | Icon | Description |
|---|---|---|
| Person | User | A user, worker, or actor |
| Step | Cog | An action or process |
| Storage | Database | Holds data, items, or state |
| Decision | GitBranch | Routes to different paths |
| Trigger | Zap | Starts a flow or process |
| Tool | Wrench | An external service or resource |
| Channel | ArrowLeftRight | A communication path |
These blocks map to anything. A “Step” can be a microservice, a kitchen station, or an assembly line stage. A “Person” can be a user, a nurse, or a delivery driver. The AI handles the domain-specific details when you describe your system.
Component properties
Section titled “Component properties”Every component supports:
- Name - Display label on the canvas
- Description - Hover card detail text
- Metrics - Throughput, capacity, processing time (see Metrics below)
- Requirements - Framework, language, runtime, OS, hardware, dependencies
- Cost - Monthly and setup cost estimates
- Infrastructure - Protocol (HTTP, gRPC, WebSocket, AMQP, Kafka, TCP, UDP, GraphQL, MQTT) and scaling config (min instances, max instances, scale trigger expression)
- Behavior - Programmable processing mode (see Behaviors)
- Subsystem - Drill into a component as its own nested system
Metrics
Section titled “Metrics”Metrics define the performance characteristics of a component. They affect simulation behavior and what numbers the AI uses when generating code or analyzing your design.
| Metric | What it means | Example values |
|---|---|---|
| Throughput (req/s) | How many requests the component handles per second at normal load | API: 500, Database: 1000, Human worker: 2 |
| Capacity | Maximum concurrent requests the component can hold or process | Queue: 100, Server: 50, Worker: 5 |
| Processing time (ms) | How long one request takes to process end to end | Cache hit: 5, API call: 200, ML inference: 2000 |
These values drive the simulation engine and stress testing. The AI also references them when generating code (e.g. setting thread pool sizes from capacity, or adding time.sleep() from processing time).
How to think about each metric:
- Throughput is your steady-state rate. Ask: “How many requests per second does this handle under normal conditions?”
- Capacity is your ceiling. Ask: “How many things can be in-flight at once before we start dropping or queuing?”
- Processing time is your latency. Ask: “How long does a single request take from start to finish?”
Real-world examples:
| Component | Throughput | Capacity | Processing time |
|---|---|---|---|
| Coffee shop register | 2 req/s | 1 | 500ms |
| REST API gateway | 500 req/s | 100 | 50ms |
| PostgreSQL database | 1000 req/s | 200 | 10ms |
| ML prediction service | 20 req/s | 5 | 2000ms |
| Message queue (Kafka) | 10000 req/s | 500 | 2ms |
| Human reviewer | 0.1 req/s | 1 | 10000ms |
Tips:
- Leave metrics at
0if you don’t know yet. The AI can suggest values based on your component’s description. - Use round numbers to start (100 req/s, 50ms). Refine after running a simulation.
- Compare metrics across components to spot bottlenecks: if your API handles 500 req/s but your database handles 100, the database is the constraint.
Infrastructure
Section titled “Infrastructure”The Infrastructure section lets you define how a component communicates and scales.
Protocol sets the primary communication protocol for the component. This affects AI code generation (appropriate client libraries) and the deterministic Python export (protocol-aware imports).
| Protocol | Typical use |
|---|---|
| HTTP | REST APIs, web services |
| gRPC | Internal microservice RPC |
| WebSocket | Real-time bidirectional streams |
| AMQP | Message broker integration (RabbitMQ) |
| Kafka | Event streaming |
| TCP / UDP | Low-level network services |
| GraphQL | Query-based APIs |
| MQTT | IoT device messaging |
Scaling defines instance boundaries and autoscale triggers:
- Min instances - Minimum replica count (baseline capacity)
- Max instances - Maximum replica count (scale ceiling)
- Scale trigger - Expression that triggers scaling (e.g.
cpu > 80%,queue.depth > 100)
When a component has maxInstances > 1, the Python export generates a ThreadPoolExecutor pool sized to maxInstances and the AI code generator uses concurrency patterns like thread pools or multiprocessing.