Documentation · v0.1.0

How to use CodeGuardian AI — and how it actually works.

A complete walkthrough of the product: from your first analysis to the seven-agent pipeline, the architecture underneath, and the scoring formula behind every health score.

Start readingBack to Home
Quick Start

From zero to first analysis in under two minutes

Four steps. No local install, no model wiring — sign in, point us at your code, and watch the agents work.

  1. Step 01
    Create an account

    Sign up from the home page. We provision a workspace instantly — no credit card, no GPU setup on your end.

    Sign up
  2. Step 02
    Add a repository or upload a ZIP

    Open the Repository page and connect a GitHub repo in owner/name format, or head to the Dashboard and upload a ZIP archive of your project.

    Open Repository
  3. Step 03
    Run an analysis

    Click New Analysis. The 7-agent pipeline kicks off immediately — watch each step stream live on the Agent Tasks page.

    New Analysis
  4. Step 04
    Read the report and act

    Open the analysis detail page to see bugs, vulnerabilities, and code smells with Gemma 4 explanations and suggested refactors.

    Go to Dashboard
How it works

Seven agents. One LangGraph pipeline. Full observability.

Each run executes the same seven-node graph in sequence. Every node records its kind, status, duration, and token usage to the agent_runs table — which is what the Agent Tasks page renders.

  1. Step 01repository

    Repository ingestion

    Indexes the uploaded codebundle or connected repository and prepares a structured snapshot for downstream agents.

    Streams file paths, sizes, and detected languages into pipeline state.

  2. Step 02analysis

    Scanner agent (Gemma 4)

    Reads the codebundle and emits structured findings — bugs, vulnerabilities, and code smells — with rule IDs, severity, and line ranges.

    Output is parsed through a defensive JSON extractor that strips markdown fences and extracts the object body.

  3. Step 03prioritization

    Prioritization agent

    Ranks findings by blast radius — severity, reach, and fix cost — so the highest-leverage issues surface first.

    Produces an ordered list that drives the explanation and refactor steps.

  4. Step 04explanation

    Explanation agent (Gemma 4)

    Translates each prioritized finding into plain English: what is wrong, why it matters, and the recommended fix path.

    Output is attached to every issue row and rendered on the analysis detail page.

  5. Step 05refactor

    Refactor agent (Gemma 4)

    Proposes a concrete before/after diff for the top findings, rendered inline on every issue card.

    Suggestions include before/after snippets and a rationale grounded in the explanation step.

  6. Step 06validation

    Validation agent (Gemma 4)

    Reviews each proposed fix to confirm it addresses the finding without introducing new issues. No credit for fixes that do not hold up.

    Emits a pass/fail verdict per finding, filtering out invalid suggestions before the report.

  7. Step 07report

    Report composer

    Stitches everything into a single composite score, a counts summary, and a markdown report ready to share.

    Final state is persisted to Supabase and surfaced across the dashboard.

Architecture

A multi-agent stack wired for transparency

Every layer is intentionally observable — from the LLM provider down to the per-node token counts. Here are the six planes that make up CodeGuardian AI.

Next.js
Frontend
  • App Router with Server Components
  • TanStack Query for analysis polling
  • Tailwind CSS + shadcn/ui primitives
  • Supabase Auth session forwarding
FastAPI
Backend
  • Async Python routers under /api/*
  • Pydantic v2 validation at every boundary
  • Service layer isolates the Supabase client
  • Background analysis runner with live progress
Gemma 4 · MI300X
LLM serving
  • google/gemma-4-26B-A4B-it (MoE, 4B active)
  • vLLM 0.23 on AMD MI300X (bf16)
  • OpenAI-compatible endpoint at /v1
  • 8192 context, streaming responses
LangGraph
Orchestration
  • 7-node StateGraph compiled once at startup
  • Per-node agent_runs rows for observability
  • Defensive JSON parsing for fenced model output
  • Typed AgentState shared across nodes
Supabase
Data layer
  • Postgres tables: analyses, issues, agent_runs, repos
  • Row-level security scoped to auth.uid()
  • Storage bucket for ZIP uploads
  • Server-side admin client for service writes
AMD Developer Cloud
Infrastructure
  • MI300X droplet with vLLM front-end
  • FastAPI behind uvicorn with --reload in dev
  • Supabase project for auth + database
  • Environment-driven config via pydantic-settings
Health Score

A capped-penalty formula that rewards progress

Each category contributes a bounded penalty. Caps mean a single noisy category cannot crater the score to zero — fix the worst bucket first and watch the number climb.

The formula
score = max(
  0,
  100
    - min(bugs_count            * 8,  40)
    - min(vulnerabilities_count * 12, 50)
    - min(code_smells_count     * 3,  15)
)
CategoryPenalty per itemCategory cap
Bugs-8max -40
Vulnerabilities-12max -50
Code smells-3max -15

Example: 3 bugs, 1 vulnerability, 10 code smells = (3x8) + (1x12) + (10x3) = 66 penalty, final score 34/100. Fix the vulnerability and 2 bugs to get (1x8) + 0 + (10x3) = 38, score 62/100.

Inside the app

Five pages, one workflow

The sidebar navigation maps directly onto the analysis lifecycle — from starting a run to inspecting agent traces and acting on issues.

Dashboard
/dashboard

Your landing pad inside the app. Shows KPI cards (analyses run, average health score, total issues found), the recent scans table, and the entry point to start a new analysis.

Issues
/issues

Aggregated insights from your most recent analysis. Bug, vulnerability, and code smell counts with a deep-link into the full issue list.

Agent Tasks
/agent-tasks

Real-time view of LangGraph node executions. KPI cards for total, completed, and failed runs and token usage, plus a table of every step with its status, duration, and parent analysis.

Repository
/repository

Connect and manage GitHub repositories. Each repo stores owner/name, default branch, and detected language. ZIP uploads skip this page entirely and go straight to analysis.

Settings
/settings

Workspace preferences, plan, and notification configuration. Standard Plan defaults apply during the hackathon demo.

FAQ

Common questions, straight answers

If something else is unclear, the Support page has contact details — we are happy to dig in.

Do I need to bring my own GPU or API key?

No. CodeGuardian AI runs Gemma 4 on an AMD Developer Cloud MI300X instance. The vLLM endpoint is already live — you just sign in and run analyses.

What languages are supported?

Anything Gemma 4 can reason about. The scanner agent is language-agnostic at the prompt level; structured findings come back as bugs, vulnerabilities, or code smells with file paths and line numbers.

Why did my analysis finish in under 5 seconds with no issues?

That was a known issue where Gemma 4 wrapped its JSON output in markdown fences and the parser silently swallowed the error. It has been fixed — every node now uses a defensive JSON extractor that strips fences and extracts the object body. If you see 0 issues on a real codebase, retry the upload.

How long should a full analysis take?

Between 20 and 90 seconds depending on codebundle size and model load. Each of the seven pipeline steps is recorded with its own duration in the Agent Tasks page, so you can see exactly where time is spent.

Can I edit a suggested refactor?

The refactor agent proposes diffs for the top-priority findings. The current demo surfaces the suggestion inline; full approve/edit/iterate flows are on the roadmap.

Where is my code stored?

Uploaded ZIP archives land in a Supabase Storage bucket. Repository metadata (owner/name, branch, language) lives in Postgres. CodeGuardian never persists the raw file contents beyond the analysis run.

What happens if a pipeline node fails?

The failing step is marked with status=failed in agent_runs, the error message is captured, and the overall analysis transitions to failed state. You can inspect the failure from the Agent Tasks table.

Ready to see it in action?

Run your first analysis in under two minutes. No setup, no API keys, no GPU required.

Start freeBack to Home