# team-atlanta/aixcc-afc-p4 architecture

> Architecture diagram of the GitHub repository team-atlanta/aixcc-afc-p4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/team-atlanta/aixcc-afc-p4
- Repository: https://github.com/team-atlanta/aixcc-afc-p4

## Overview

##### Project type and purpose
- This is a Python library (open-source tool) named “P4” for automated vulnerability analysis and patching.
- It leverages LLMs (via LangChain, OpenAI), reinforcement learning, AST-based pattern matching, and dynamic model fine-tuning (LoRA) to parse crash logs, detect vulnerable code patterns, and generate targeted patches.

##### File structure
- Top-level packages:
- p4_core: The core engine, subdivided into five layers (environment, pattern, policy, runnable, scope).
- p4: The high-level framework that ties together document management, tools, AI environment, patch generation, and model adaptation.
- Supporting files:
- pyproject.toml / uv.lock: Build/dependency management.
- .vscode / .python-version / .gitignore: Dev/configuration files.
- Naming conventions (protocols, models) indicate a type-safe, protocol-oriented design with clear extension points.

##### README for architectural insights
- The README defines five “Core Components” in p4_core, then describes the “Main Framework” in p4, listing:
- Document Management (BaseDocument, TextDocument, FileDocument)
- Tools (e.g., CppFunctionDefinitionTool)
- AI Environment (AIxCCEnvironment)
- Patch Generation (LangChain + VFS)
- Model Adaptation (LoRA client)
- External dependencies (pydantic, langchain-core, ast-grep-py, joblib, etc.) show integration points.

1. Pattern Layer (p4_core.pattern)
2. Policy Layer (p4_core.policy)
3. Environment Layer (p4_core.environment)
4. Runnable Layer (p4_core.runnable)
5. Scope Layer (p4_core.scope)
6. Document Management (p4 module)
7. Analysis Tools (CppFunctionDefinitionTool, JavaMethodDeclarationTool)
8. AI Environment (AIxCCEnvironment)
9. Patch Generation Engine (LangChain integration + Virtual File System)
10. Model Adaptation (LoRA Client)
11. External Services/APIs (OpenAI, ast-grep-py, ripgrepy, joblib)

1. Crash log & source files → Document Management → Fragmented code & metadata
2. Documents + Patterns → Pattern Layer → Identified code fragments
3. Fragments → Policy Layer → LLM prompts/responses (via LangChain & OpenAI)
4. Policy decisions → Environment Layer → Step-based simulation (training/inference)
5. Runnable Layer handles generic execution errors & orchestrates tool runs
6. Scope Layer provides isolated sandbox contexts for tool execution
7. Analysis Tools ↔ Scope & Environment (parallel execution via joblib)
8. Policy & Environment → Patch Generation Engine → Virtual File System edits
9. Model Adaptation monitors vulnerability context → LoRA Client for on-the-fly fine-tuning

c. Architectural patterns and design principles:
- Protocol-oriented, type-safe interfaces (BasePattern[T], BasePolicy, BaseEnvironment, BaseRunnable)
- Layered architecture for separation of concerns
- Plugin/extensibility points at each layer via Python Protocols
- Parallelism (joblib) and sandboxing (Scope) for safe, scalable analysis

d. Key technologies/frameworks (annotate each component):
- pydantic: Data modeling in Policy & Environment
- LangChain & openai: LLM orchestration in Policy & Patch Generation
- ast-grep-py / ripgrepy: Pattern matching in Pattern Layer
- joblib: Parallel execution in AI Environment
- Virtual File System: In-memory patch management
- LoRA: Model adaptation

##### Essential architectural elements
- Layers in p4_core and the high-level modules in p4.
- How LLM integration, pattern matching, and RL converge in the AI environment.
- Patch generation workflow and model adaptation loop.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs
    Logs["Crash Logs"]:::external
    Src["Source Files"]:::external

    %% Core Engine Package
    CE["p4_core Package"]:::core
    click CE "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/__init__.py"
    PT["py.typed"]:::core
    click PT "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/py.typed"

    %% Core Layers
    subgraph "Core Engine Layers"
        subgraph "Pattern Layer"
            PL["Pattern Layer"]:::core
            PP["protocols.py"]:::core
            PM["models.py"]:::core
            click PL "https://github.com/team-atlanta/aixcc-afc-p4/tree/main/p4_core/pattern/"
            click PP "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/pattern/protocols.py"
            click PM "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/pattern/models.py"
        end
        subgraph "Policy Layer"
            PoL["Policy Layer"]:::core
            PPo["protocols.py"]:::core
            PMo["models.py"]:::core
            click PoL "https://github.com/team-atlanta/aixcc-afc-p4/tree/main/p4_core/policy/"
            click PPo "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/policy/protocols.py"
            click PMo "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/policy/models.py"
        end
        subgraph "Environment Layer"
            EL["Environment Layer"]:::core
            EP["protocols.py"]:::core
            click EL "https://github.com/team-atlanta/aixcc-afc-p4/tree/main/p4_core/environment/"
            click EP "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/environment/protocols.py"
        end
        subgraph "Runnable Layer"
            RL["Runnable Layer"]:::core
            RP["protocols.py"]:::core
            click RL "https://github.com/team-atlanta/aixcc-afc-p4/tree/main/p4_core/runnable/"
            click RP "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/runnable/protocols.py"
        end
        subgraph "Scope Layer"
            SL["Scope Layer"]:::core
            SP["protocols.py"]:::core
            click SL "https://github.com/team-atlanta/aixcc-afc-p4/tree/main/p4_core/scope/"
            click SP "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4_core/scope/protocols.py"
        end
    end

    %% High-Level Framework Package
    HL["High-Level Framework (p4)"]:::framework
    click HL "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4/__init__.py"
    HLT["py.typed"]:::framework
    click HLT "https://github.com/team-atlanta/aixcc-afc-p4/blob/main/p4/py.typed"

    %% Framework Modules
    subgraph "Framework Modules"
        DM["Document Management"]:::framework
        AT["Analysis Tools"]:::framework
        AE["AI Environment"]:::framework
        PG["Patch Generation Engine"]:::framework
        MA["Model Adaptation"]:::framework
    end

    %% External Dependencies
    subgraph "External Dependencies"
        OAI["OpenAI"]:::external
        LC["LangChain"]:::external
        AG["ast-grep-py / ripgrepy"]:::external
        JB["joblib"]:::external
        VFS["Virtual File System"]:::external
        LORA["LoRA Client"]:::external
    end

    %% Data Flow
    Logs --> DM
    Src --> DM
    DM --> PL
    PL --> PoL
    PoL --> EL
    EL --> RL
    RL --> SL

    %% Tool & Environment Interaction
    AT <--> SL
    AT <--> EL

    %% Patch Generation & Adaptation
    PoL --> PG
    EL --> PG
    PG --> VFS
    MA --> LORA

    %% AI Orchestration
    PoL --> OAI
    PoL --> LC
    PG --> LC
    AE --> JB

    %% Pattern Matching
    PL --> AG

    %% Class & Package relations
    CE --> PL
    CE --> PoL
    CE --> EL
    CE --> RL
    CE --> SL
    HL --> DM
    HL --> AT
    HL --> AE
    HL --> PG
    HL --> MA

    %% Styles
    classDef core fill:#add8e6,stroke:#000,color:#000;
    classDef framework fill:#98fb98,stroke:#000,color:#000;
    classDef external fill:#ffcc99,stroke:#000,color:#000;
```
