Quickstart
C4CI generates your first C4 architecture diagram from Azure infrastructure in under 2 minutes. Connect your subscription with Reader role — no write permissions required — run a scan, and your L1 System Context diagram appears automatically.
The platform reads from Azure Resource Graph. No agents to install, no SDKs to integrate, no changes to your infrastructure. You grant the Reader role once via Azure Portal or CLI, and the platform handles discovery from there.
Path to first diagram:
- Create a project and add your Azure Subscription ID now, or save it for the project page if you're still waiting on access
- Grant Reader role to the C4CI platform identity (shown on the project page)
- Click Verify connection, then Run scan
- Open the L1 diagram — target: under 10 minutes total
Prerequisites
- An Azure subscription (or access to one)
- Permission to grant the Reader role on that subscription — either as Owner, User Access Administrator, or by asking your Azure admin
Key concepts
C4CI organises work in two levels: Organisation and Project.
- Organisation — your top-level billing and access boundary. Typically one per company or team. All projects, members, and billing belong to one organisation. You can create multiple organisations if you work across different clients or teams.
- Project — one project connects one Azure subscription to C4CI. Each project has its own scan history, diagrams, and drift state. On Pro and Enterprise tiers, you can create unlimited projects (one per subscription).
Step 1 — Sign in
Register or sign in using Microsoft Entra ID, Google, GitHub, or a local email account. All sign-in methods are equivalent — you can link additional providers later from Settings → Account.
Step 2 — Create an Organisation
On first sign-in you'll be prompted to create an Organisation. Give it a name (e.g. your company name) and a URL slug (e.g. acme-corp). This is your billing entity — all projects and team members belong to it. You can rename it later from Settings → Organisation.
Step 3 — Create a Project
From Projects, click New project. You'll need three things:
- Project name — e.g.
productionordev-cluster. This is internal to C4CI; it doesn't need to match any Azure resource name. - Azure Subscription ID — a UUID in the format
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Find it in Azure Portal → Subscriptions, or via CLI:az account show --query id. - Azure Tenant ID — optional. Required only if your subscription belongs to a different Entra tenant than your C4CI login. Find it in Azure Portal → Microsoft Entra ID → Overview.
Once the project is created, you'll land on the project overview page. The "Connect Subscription" section shows the C4CI platform identity that needs the Reader role — copy that identity name before moving to Step 4.
Step 4 — Grant Reader Role
C4CI scans your Azure resources via Azure Resource Graph. It requires the Reader role on your subscription — no Contributor, Owner, or write permissions of any kind. This is a permanent architecture decision: C4CI never mutates your infrastructure.
Grant the role in Azure Portal in three steps:
- Go to Azure Portal → Subscriptions → [your subscription] → Access control (IAM)
- Click Add → Add role assignment. Select the Reader role, then click Next.
- Under "Members", select Managed identity (for same-tenant setups) or User, group, or service principal (for cross-tenant). Paste the C4CI platform identity name from the project page. Save.
Back on the C4CI project page, click Verify connection. The platform confirms it can read your subscription. If verification fails, the most common cause is propagation delay — Azure RBAC changes typically take 1–2 minutes to propagate. Wait a moment and try again.
Cross-tenant setups:If your Azure subscription belongs to a different Entra tenant than your C4CI sign-in (common for consultants and agencies), use the "Use your own credentials" option in the Connect Subscription section and provide an App Registration client ID and secret with Reader scope.
Step 5 — Run a Scan
From the project page, click Run scan. The platform queries Azure Resource Graph across your subscription and builds a C4 model. For most subscriptions this takes under 2 minutes. Subscriptions with 500+ resources may take 3–5 minutes.
The scan is read-only. Nothing in your Azure environment is modified. The platform discovers resource types, relationships, and metadata — then stores the C4 model snapshot in your project.
Free tier gives you L1 (System Context) and L2 (Container) diagrams immediately. Pro tier adds L3 (Component) and K8s drill-down. Enterprise adds L4 (Code-level) and drift detection.
Step 6 — Open the L1 Diagram
After the scan completes, the portal redirects you to the L1 diagram automatically. The L1 System Context diagram shows your Azure subscription as a single system boundary, with external actors (users, external services) and the major containers visible at the top level.
From the diagram view you can: switch between L1, L2, and L3 (Pro+); export to PDF or PlantUML for design reviews and version-controlled architecture docs; enable drift detection to compare this scan against a future scan; and — on Enterprise/PAYG — generate OpenTofu code from diagram changes.
What each diagram level shows
| Level | What you see | Tier |
|---|---|---|
| L1 — System Context | Your subscription as a system boundary, external actors, top-level resource groups | Free |
| L2 — Container | Applications, data stores, messaging, and the connections between them | Free |
| L3 — Component | Internal structure of containers — services, functions, queues | Pro+ |
| L4 — Code | OTel traces + GitHub code analysis — class/method level | Enterprise / PAYG |
Common issues
Verification fails immediately
Azure RBAC changes take 1–5 minutes to propagate. Wait a moment after granting Reader role, then click Verify again. If it still fails, confirm the identity name in the project page matches exactly what you assigned in Azure IAM.
Scan returns 0 resources
This usually means the Reader role was granted at the resource group level rather than the subscription level. C4CI needs Reader at the subscription scope to query Resource Graph across all resource groups. Go to Azure Portal → Subscriptions → [your subscription] → Access control (IAM) and confirm the role assignment is there.
Scan is slow (more than 5 minutes)
Large subscriptions (1,000+ resources) take longer. This is expected. The scan progress bar on the project page updates in real time. If a scan has been running for more than 15 minutes, contact support.
Frequently asked questions
How long does the first scan take?
Under 2 minutes for most Azure subscriptions. Subscriptions with 500+ resources may take 3–5 minutes. The scan queries Azure Resource Graph — scan duration scales with resource count, not subscription age.
What if I don't have permission to grant Reader role?
Ask your Azure subscription Owner or User Access Administrator to grant the Reader role to the C4CI platform identity. You'll see the exact identity (Managed Identity or App Registration) on the project's Connect Subscription page.
Can I connect multiple Azure subscriptions?
Free tier: 1 subscription. Pro and Enterprise: unlimited subscriptions, each as a separate project. PAYG: billed per subscription per scan.
Why does C4CI only need Reader role?
C4CI reads from Azure Resource Graph to discover resources and build diagrams. It never writes to your subscription. The read-only model is a permanent architecture decision — not a feature flag. The write path (generating OpenTofu code) produces code you review and apply yourself.
Next steps
- View pricing — compare Free, Pro, Enterprise, and PAYG tiers
- Architecture metrics — how drift and risk scores are calculated
- Live demo — explore a pre-loaded Azure architecture before connecting your own
- Contact us — questions or enterprise inquiries
Platform operators
Deploying C4CI infrastructure, addons, or running the full stack? See the Golden Path documentation for deployment order, value sources, and workflow triggers.