Genesis Scan

Genesis Scan provides one-click, AI-driven analysis of an entire codebase. It connects to your GitHub repository, downloads the source files, chunks them for processing, and runs each chunk through Gemini AI across seven specialized analysis layers. The result is a comprehensive set of findings that are assembled into your project brain as searchable memory items.

Why Genesis Scan exists

AI coding assistants are only as effective as the context they receive. Without deep project understanding, they hallucinate APIs, misuse conventions, and produce code that does not fit the codebase. Genesis Scan solves this by giving the AI instant, structured knowledge about your project -- from business logic down to security vulnerabilities -- without requiring manual documentation.

The 7 analysis layers

Genesis Scan examines your codebase through seven distinct layers. Each layer targets a different dimension of the project, ensuring comprehensive coverage.

Product layer

The product layer identifies what the application does from a user's perspective. It extracts user flows, business rules, and feature boundaries. This helps the AI understand the "why" behind the code, not just the "how".

Architecture layer

The architecture layer maps the technical structure: frameworks, design patterns, folder conventions, and how components connect. It produces a high-level blueprint of the system.

Dependencies layer

The dependencies layer analyzes package.json, lock files, and import statements to understand which libraries are used, their versions, and how they are integrated. This prevents the AI from suggesting incompatible packages or deprecated APIs.

Conventions layer

The conventions layer detects coding patterns, naming conventions, and organizational rules. It captures implicit team agreements that would normally require reading hundreds of files to understand.

Data Model layer

The data model layer extracts database schemas, TypeScript types, API request/response shapes, and data flow patterns. This gives the AI accurate knowledge of data structures throughout the application.

Entry Points layer

The entry points layer catalogs all routes, pages, middleware, and public exports. It builds a map of the application's surface area -- every way a user or system can interact with the codebase.

Security layer

The security layer performs an OWASP-based vulnerability scan, checking for common security issues like injection risks, authentication weaknesses, and sensitive data exposure. This layer is optional and can be toggled when starting a scan.

The 8 phases of a scan

A Genesis Scan progresses through eight sequential phases. Each phase must complete before the next begins.

graph LR
    A[fetch_tree] --> B[fetch_files]
    B --> C[build_chunks]
    C --> D[analyze]
    D --> E[synthesize]
    E --> F[security_audit]
    F --> G[assemble]
    G --> H[complete]

    style A fill:#1a1a2e,stroke:#FF5C00,color:#fff
    style B fill:#1a1a2e,stroke:#FF5C00,color:#fff
    style C fill:#1a1a2e,stroke:#FF5C00,color:#fff
    style D fill:#1a1a2e,stroke:#FF5C00,color:#fff
    style E fill:#1a1a2e,stroke:#FF5C00,color:#fff
    style F fill:#1a1a2e,stroke:#FF5C00,color:#fff,stroke-dasharray: 5 5
    style G fill:#1a1a2e,stroke:#FF5C00,color:#fff
    style H fill:#1a1a2e,stroke:#FF5C00,color:#fff

Selective vs Full scan

Genesis Scan supports two modes:

Full scan

A full scan analyzes every file in the repository. Use this for the initial scan of a project or when you want to rebuild the analysis from scratch.

Selective scan

A selective scan only re-analyzes files that have changed since the last scan. It compares the current file tree against the previous scan's tree and processes only new or modified files. This is significantly faster and cheaper than a full scan.

Selective scans produce a diff summary showing new, updated, and removed findings compared to the previous scan.

How findings become brain items

During the assemble phase, each finding is converted into a brain item:

1. Type classification -- Each finding is tagged with its analysis layer (product, architecture, etc.)
2. Importance scoring -- Findings are scored from 1 to 5 stars based on their significance to the project
3. File references -- Source files that contributed to the finding are attached
4. Schema key assignment -- Findings are mapped to appropriate schema keys in the brain hierarchy (e.g., root/genesis/architecture)
5. Tech stack extraction -- Technology references are extracted and tagged as tech stack badges
6. Brain insertion -- Items are written to the project brain and become immediately searchable

Pipeline architecture

The full Genesis Scan pipeline flows from the dashboard UI through the API to a background worker:

sequenceDiagram
    participant User
    participant Dashboard
    participant API
    participant Worker
    participant GitHub
    participant Gemini
    participant Brain

    User->>Dashboard: Click Start Scan
    Dashboard->>API: POST /api/v2/genesis/start
    API->>Worker: Queue scan job
    Worker->>GitHub: Fetch repository tree
    GitHub-->>Worker: File list
    Worker->>GitHub: Download files
    GitHub-->>Worker: File contents
    Worker->>Worker: Build chunks
    Worker->>Gemini: Analyze chunks (7 layers)
    Gemini-->>Worker: Raw findings
    Worker->>Worker: Synthesize findings
    Worker->>Gemini: Security audit (optional)
    Gemini-->>Worker: Security findings
    Worker->>Brain: Assemble into brain items
    Worker-->>API: Update scan status
    API-->>Dashboard: Progress updates
    Dashboard-->>User: Results view

Next steps

• Genesis Dashboard -- How to use the Genesis UI
• V2 Genesis API -- API reference for Genesis endpoints
• Codebase Scanner -- The lightweight CLI alternative