PinPole User Guide — Shared features
Version 2.0 · Provider-agnostic chapters
This document replaces Sections 1–13, 17–21 of the former single-file PinPole User Guide v1.0 (AWS-only). It applies to all supported clouds unless a topic explicitly defers to an AWS / Azure / GCP supplement.
1. What PinPole is
PinPole is a browser-based cloud architecture design platform. You compose services on a canvas, connect them to represent traffic and dependencies, simulate load from small RPS to very large scale, review cost and behaviour, and apply AI recommendations — largely before you spend on provisioned infrastructure.
Multi-cloud: The same core workflow applies when your workspace targets AWS, Azure, or Google Cloud (GCP). Provider-specific deploy, quotas, and some export details live in:
Deep product positioning: What is PinPole?. Audience and plans: Who this guide is for, Plans & feature availability.
2. Core concepts
| Concept | Description |
|---|---|
| Workspace / project | Container for canvases and metadata; may be tied to a cloud provider for new diagrams. |
| Canvas | Visual editor: service nodes, edges, optional text and group annotations. |
| Node | A configured service instance (or annotation). Selection opens Node configuration. |
| Simulation | Traffic-driven run that produces metrics, alerts, and cost signals for the current graph. |
| Recommendations | AI-generated improvements (cost, latency, resilience); can be applied to the canvas. |
| Execution history | List of past runs with status, load, duration, estimated $/mo, alerts, and applied recommendation counts. |
3. Getting started
Minimal path:
- Open the app and select or create a project and workspace.
- Drag services from the palette onto the canvas (provider matches your workspace).
- Connect nodes in valid directions; PinPole blocks incompatible wiring.
- Open each node’s configuration and set realistic parameters.
- Run simulation with a traffic pattern and target RPS.
- Review metrics, alerts, and recommendations; apply changes intentionally.
- Iterate — compare runs via execution history where available.
Detailed checklist: Before you start. Canvas UI (toolbar, pan, export, annotations): Canvas & UI overview.
4. Infra Architect Agent
Infra Architect Agent is PinPole’s AI architecture assistant, distinct from post-simulation “recommendations.”
4.1 Chat-to-canvas
- Open the AI Architect control on the canvas toolbar (sparkles).
- Describe the workload in natural language (ingress, compute, data, messaging, scale, compliance hints).
- The assistant streams thinking steps (requirements, topology, security, cost, etc.) and, when appropriate, proposes a graph of nodes and edges.
- You can apply the generated architecture to the canvas; the app can fit view and tidy layout after generation.
4.2 Diagram-to-canvas
- Inside the same panel you can upload an architecture diagram (image).
- The assistant can analyse the image and help recreate or refine topology on the canvas (behaviour depends on model and backend).
Full UI reference: AI Architect chat. Simulation-time AI tuning: AI recommendations.
5. Canvas and tooling
5.1 Palette and providers
- The left palette lists services for the active provider (AWS / Azure / GCP).
- Search and categories reduce scrolling; drag nodes to place them.
5.2 Toolbar highlights
- Pointer / pan — select vs move viewport.
- Export PNG — snapshot of the diagram.
- Theme — light/dark canvas chrome.
- Auto organise — best-effort layout tidy.
- AI Architect — Infra Architect Agent (see §4).
- Text annotation — double-click to edit free text.
- Group frame — dashed border with title; resize for logical grouping (visual only, not a live VPC/subnet envelope).
Details: Canvas tools & toolbar. Capability limits (zones, async edge semantics): Canvas capabilities.
6. Configuring services
Each service node exposes a Node configuration panel:
- Collapsible sections (titles match in-app groups).
- Field types: text, number, toggles, selects — with hints for scale and cost impact.
- Quick actions on supported services (shortcuts for common ops in the product).
- Infrastructure placement appears for all three providers (VPC/VNet/network name, zone/region, subnet type).
Authoritative list of services and section names: Cloud services catalog. Panel behaviour: Node configuration. Workflow: Configure services.
7. Simulation
7.1 Traffic and runs
- Choose a traffic pattern (e.g. steady, ramp, burst) and RPS targets.
- Start Simulate; you can pause/resume depending on product mode.
- While running, use live views and panels as documented in Run simulation.
7.2 Interpreting results
- Latency, throughput, throttling, and cost views help locate bottlenecks.
- Alerts flag inconsistencies or quota pressure.
- Read Interpret results and Optimisation patterns.
8. Recommendations and applying changes
After (or during) simulation, AI recommendations may suggest concrete parameter or topology changes.
- Review severity and rationale before applying.
- Apply one change at a time when learning cause and effect.
- Some behaviours (e.g. concurrency-related) require stopping and restarting a simulation to pick up new parameters — see FAQ.
Workflow: AI recommendations.
9. Execution history
Execution history lists simulation runs associated with your workspace. Each row summarises:
| UI element | Meaning |
|---|---|
| Status | e.g. completed, running — shows outcome of that run. |
| Run index | #n — order among stored runs (newer/older orientation follows the panel). |
| Peak RPS | Load peak for that execution. |
| Duration | How long the run lasted. |
| $/mo | Estimated monthly cost signal from that run’s configuration (saved snapshot for comparison, not a billing invoice). |
| Throttled / alerts | Quick badges when nodes were throttled or issues were raised. |
| Applied | x/y applied — recommendations applied out of the total suggested for that run. |
Expand a run for tabs such as Overview, Recommendations, and Nodes to inspect details. Multiple runs unlock messaging about side-by-side comparison (feature evolution may add full diff UI).
Related: Iterate & version.
10. Infrastructure code generation
PinPole can produce infrastructure representations from the canvas for use in your pipelines.
| Output style | Typical use |
|---|---|
| Terraform-oriented | HCL or intermediate definitions depending on plan and roadmap; check Export panel for current formats. |
| AWS CloudFormation | AWS stacks / templates where exposed in product for AWS diagrams. |
| AWS CDK | CDK-flavoured export for AWS where exposed. |
Per provider: exact formats and maturity differ. AWS is the most complete today; Azure and GCP exports follow the same product direction — see the AWS, Azure, and GCP supplements.
Roadmap note: full Terraform HCL code generation (beyond definitions) is tracked in Roadmap. Deploy workflow: Deploy to AWS (live AWS path).
11. Export — JSON, Terraform, PNG, GIF
From the canvas and related panels you can export artefacts for sharing and CI integration.
| Format | Role |
|---|---|
| JSON | Machine-readable architecture / project payload for tooling, backups, or integrations (availability depends on product surface). |
| Terraform | As above — IaC alignment for Terraform workflows. |
| PNG | Static image of the canvas — presentations, wiki, reviews. |
| GIF | Animated capture of simulation or canvas activity when the product exposes recording — useful for demos and stakeholder updates. |
Toolbar Export PNG is documented in Canvas tools & toolbar. Supplementary provider notes: AWS / Azure / GCP guides.
12. Deploy to Cloud (summary)
| Provider | Deploy to Cloud |
|---|---|
| AWS | Live — cross-account IAM via STS; review plan then provision. See AWS supplement and Step 7 — Deploy to AWS. |
| Azure | Coming soon — design and simulate on Azure today; direct deploy from PinPole is on the roadmap. |
| GCP | Coming soon — same pattern: parity on canvas first, managed deploy follows. |
Always deploy to non-production first and record which simulation run validated the architecture.
13. Cloud Terminal
The Cloud Terminal is a CLI-style surface in the product used to query simulated state, explore quotas and behaviour, and experiment with configuration questions without leaving the session.
All three providers: Cloud Terminal is available for AWS, Azure, and GCP contexts according to your workspace and feature flags — not AWS-only.
Details: Cloud Terminal.
14. Enterprise and collaboration
Team features, seats, and shared workspaces: Enterprise workflows, Plans & pricing, Add-ons.
15. FAQ (shared highlights)
| Topic | Answer |
|---|---|
| Multi-cloud | PinPole supports AWS, Azure, and GCP on the canvas; Deploy to Cloud is live for AWS; Azure and GCP deploy are coming soon. |
| Account required? | No cloud account is required to design and simulate; an account is required when you use Deploy to Cloud (or future provider equivalents). |
| Infra Architect vs recommendations | Infra Architect Agent helps author or import topology from chat/diagrams; recommendations tune an existing simulated architecture. |
| Simulation packs | Purchasable add-on when you exhaust plan runs — see FAQ. |
Full FAQ: FAQ.
16. Roadmap (snapshot)
High-level phases are maintained in Upcoming Features & Roadmap. Expect continuous delivery within each phase — multi-cloud canvas and agent features evolve ahead of full Deploy to Cloud parity.
17. Related deep references
- Worked example
- PinPole vs AWS native tools
- AWS service reference notes (AWS-deep content)
End of shared features guide. Open your provider supplement next: AWS · Azure · GCP.