Getting started

Your first review should leave you with a system you can explain: the parts, their relationships, the observations supporting them, and the boundaries of what is known.

1. Create your workspace

Create an account or accept a team invitation, complete email verification, and name your workspace. You can create the workspace before connecting a provider. A GitHub account is not required.

Your workspace holds source connections, reviews, architectural evidence, decisions, and team access. Roles control who may connect sources, run reviews, and approve a decision. See workspace access for account and role details.

2. Create your project

Open Project brain → New project. Name the application, choose its work prefix, and record what it does, who it serves, goals, and constraints. The project can exist before a source is connected. See your project brain.

3. Choose your first source

Open Sources to connect a selected GitHub, GitLab, or Bitbucket project, or upload a source ZIP. Include the application's infrastructure and delivery configuration when they are available.

CodeCloudIaCCI/CD

Start with the application you want to understand.

Connect a selected GitHub, GitLab, or Bitbucket repository, or upload a source archive. A workspace does not require a GitHub account.

What it contributes

Services, imports, dependencies, API definitions, calls, and data access found in the submitted revision.

What remains unknown

A source snapshot cannot establish the current deployed state or prove that a particular path was exercised in production.

Choose a code source

Cloud collection is a separate source of observed environment configuration. Follow the cloud collector guide to submit a bounded AWS, Azure, or Google Cloud inventory. A repository connection by itself does not connect a cloud account.

After connecting, return to Project brief and select which repositories and accepted tool evidence belong to this project. Connections are shared by the workspace; the project selection bounds its brain and agent.

4. Start a review

Choose a permitted source revision or a validated upload and start a review. The audit page shows queue and stage progress. A successful or partial review becomes available in Architecture; partial results can contain useful evidence with visible collection gaps.

If the source is still validating, wait for it to become ready. If collection fails, read the reported reason before retrying. You can inspect the review lifecycle for the meaning of each stage.

5. Follow one relationship

Open Architecture → Map and select an entity from the project’s selected sources. Use Review snapshots to inspect a specific completed review. Read How this entity connects, then select a relationship. Open Truth to inspect its evidence, confidence, collection time, and any contradictions.

Use 2D for a flat reading of the system or 3D to explore depth. The map supports search, layer filtering, zoom, camera controls, and a D2 source export. These are views of the same evidence model.

Open Coverage before assuming that the map describes the whole system. Check observed source families and gaps for the selected review. Read the map guide for a complete example.

6. Connect security and delivery

Open Security to review current project findings and use Track work for an issue your team will address. In Roadmap, assign the work, choose a priority, and record dependencies. Plan a Cycle around an outcome. Completing work does not verify a fix; a later review must establish that.

Read roadmaps and cycles and merge checks for checks before release. Owners can publish selected product features through Community.

7. Record a decision that matters

In Intent → Record intent, describe the observed context and the choice your team made in response. Include the rationale, an accepted trade-off, an alternative, and the guardrail that must remain true. Attach source evidence and an affected entity when appropriate.

Saving creates a proposal owned by the signed-in person. A separate, authorized human approval records the selected option, rationale, approver, and time. Read recording intent before treating a proposal as ratified.

8. Return after the system changes

Run a later review for the same connected repository. Drift compares repository snapshots and reports changes alongside source coverage. The first snapshot provides a baseline; it cannot establish drift on its own. Archive reviews can support maps and decisions but do not create repository history.

Review changed evidence against the decision's guardrails. A written guardrail needs human interpretation unless you also selected a supported structured check. Follow reviewing drift to distinguish a verified change from missing observation.