# sebuzdugan/frai architecture

> Architecture diagram of the GitHub repository sebuzdugan/frai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sebuzdugan/frai
- Repository: https://github.com/sebuzdugan/frai

## Overview

##### Project type and purpose
- FRAI is an open-source monorepo that ships three coordinated Node/TypeScript packages:
- **frai-cli**: end-user CLI for responsible AI workflows (documentation, scanning, evaluation, RAG indexing, fine-tune governance)
- **frai-core**: modular SDK powering all functionality (Questionnaire, Documents, Scanners, Rag, Eval, Finetune, Config, Providers)
- **frai-agent**: a LangChain-based conversational agent wrapping frai-core for natural-language orchestration

##### File structure
- Top-level: monorepo config (pnpm-workspace.yaml, turbo.json), lint/build configs, docs/, examples/
- packages/
- frai-core/src: core modules (config, documents, eval, finetune, providers, rag, scanners, questionnaire)
- frai-cli/src: CLI entry point, wiring to frai-core APIs
- frai-agent/src: agent definition, LangChain tool adapters to frai-core
- CI workflows under .github/workflows

##### README for additional insights
- Describes conceptual split (CLI vs. Core vs. Agent) and key workflows
- Lists core modules and high-level command flows (scan, generate docs, rag index, eval, finetune)
- Notes external dependency on OpenAI (via Providers)

##### Main components & interactions
a. **User Interfaces**
- Terminal / CI → frai-cli
- Chat UI or direct code → frai-agent
- Programmatic import → frai-core
b. **Core Layers**
- **CLI & Agent** wrappers
– CLI invokes frai-core APIs (Scanners.scanCodebase, Questionnaire.run, Documents.generate, Rag.index, Eval.run, Finetune.validate)
– Agent exposes two tools to LangChain: scan_repository & generate_responsible_ai_docs
- **frai-core SDK**
– **Config/Providers**: read .env or global config → wire up OpenAI (or other LLMs)
– **Scanners**: static analysis → detect AI indicators → return scan results
– **Questionnaire**: prompt user for feature details via Inquirer or other prompt function
– **Documents**: assemble checklist, model card, risk file from questionnaire answers
– **Rag**: split policy docs, embed via LLM → produce vector index (JSON store)
– **Eval**: baseline evaluation metrics on model outputs vs. references → JSON/Markdown report
– **Finetune**: generate templates, validate governance plans
c. **External Services and I/O**
- **OpenAI API** (or pluggable LLM provider) for AI-driven tips, embeddings, evaluations
- **File System**: read codebase, write generated docs, vector store, reports
- **PDF Converter** (optional markdown-pdf for docs export)

##### Architectural patterns & design principles
- **Monorepo + Modular Packages**: independent versioning for CLI, Core, Agent
- **Layered Architecture**: UI layer (CLI/Agent) → orchestration layer (frai-core API) → service layer (OpenAI) → persistence layer (file system, vector store)
- **Plugin-style modules**: each core capability is a self-contained module
- **Separation of concerns**:
- UI wrappers do no heavy lifting—they just call core
- Core modules focus solely on their domain

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Wrappers
    subgraph "UI Wrappers"
        CLI["frai-cli"]:::package
        Agent["frai-agent"]:::package
        Custom["Custom Integration"]:::package
    end

    %% Core SDK
    subgraph "frai-core SDK"
        CoreIndex["Entry Point\nindex.js"]:::package

        subgraph "Config & Providers"
            ConfigIndex["config/index.js"]:::module
            ConfigConsts["config/constants.js"]:::module
            ConfigPaths["config/paths.js"]:::module
            KeyStore["config/key-store.js"]:::module
            ProvIndex["providers/index.js"]:::module
            ProvConsts["providers/constants.js"]:::module
            OpenAIProv["providers/openai.js"]:::module
        end

        subgraph Scanners
            ScannersIndex["scanners/index.js"]:::module
            Detectors["scanners/detectors.js"]:::module
            ScanConsts["scanners/constants.js"]:::module
        end

        subgraph Questionnaire
            QIndex["questionnaire/index.js"]:::module
            Questions["questionnaire/questions.js"]:::module
            QConsts["questionnaire/constants.js"]:::module
        end

        subgraph Documents
            DocsIndex["documents/index.js"]:::module
            Helpers["documents/helpers.js"]:::module
            Summaries["documents/summaries.js"]:::module
            Templates["documents/templates.js"]:::module
        end

        subgraph RAG
            RagIndex["rag/index.js"]:::module
            RagConsts["rag/constants.js"]:::module
        end

        subgraph Eval
            EvalIndex["eval/index.js"]:::module
            Metrics["eval/metrics.js"]:::module
            Reporters["eval/reporters.js"]:::module
        end

        subgraph Finetune
            FTIndex["finetune/index.js"]:::module
            Schema["finetune/schema.js"]:::module
        end
    end

    %% External Services
    OpenAI["OpenAI API"]:::external
    FSInput["Codebase\n(File System)"]:::fs
    FSOutput["Generated Docs,\nReports, Indexes"]:::fs

    %% Flows
    CLI -->|"calls"| CoreIndex
    Agent -->|"calls"| CoreIndex
    Custom -.->|"optional"| CoreIndex

    CoreIndex --> ConfigIndex
    CoreIndex --> ScannersIndex
    CoreIndex --> QIndex
    CoreIndex --> DocsIndex
    CoreIndex --> RagIndex
    CoreIndex --> EvalIndex
    CoreIndex --> FTIndex

    ProvIndex --> OpenAI
    OpenAIProv --> OpenAI
    RagIndex --> OpenAI
    EvalIndex --> OpenAI

    FSInput --> ScannersIndex
    FSInput --> RagIndex
    FSInput --> QIndex

    DocsIndex --> FSOutput
    RagIndex --> FSOutput
    EvalIndex --> FSOutput
    FTIndex --> FSOutput

    %% Click Events
    click CLI "https://github.com/sebuzdugan/frai/blob/main/packages/frai-cli/src/index.ts"
    click CLI "https://github.com/sebuzdugan/frai/blob/main/packages/frai-cli/dist/index.js"
    click Agent "https://github.com/sebuzdugan/frai/blob/main/packages/frai-agent/src/index.ts"
    click Agent "https://github.com/sebuzdugan/frai/blob/main/packages/frai-agent/src/agent/executor.ts"
    click Agent "https://github.com/sebuzdugan/frai/blob/main/packages/frai-agent/src/agent/prompt.ts"
    click Agent "https://github.com/sebuzdugan/frai/blob/main/packages/frai-agent/src/cli/run.ts"
    click Agent "https://github.com/sebuzdugan/frai/blob/main/packages/frai-agent/src/tools/scan-tool.ts"
    click Agent "https://github.com/sebuzdugan/frai/blob/main/packages/frai-agent/src/tools/docs-tool.ts"
    click CoreIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/index.js"
    click ConfigIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/config/index.js"
    click ConfigConsts "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/config/constants.js"
    click ConfigPaths "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/config/paths.js"
    click KeyStore "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/config/key-store.js"
    click ProvIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/providers/index.js"
    click ProvConsts "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/providers/constants.js"
    click OpenAIProv "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/providers/openai.js"
    click ScannersIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/scanners/index.js"
    click Detectors "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/scanners/detectors.js"
    click ScanConsts "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/scanners/constants.js"
    click QIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/questionnaire/index.js"
    click Questions "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/questionnaire/questions.js"
    click QConsts "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/questionnaire/constants.js"
    click DocsIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/documents/index.js"
    click Helpers "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/documents/helpers.js"
    click Summaries "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/documents/summaries.js"
    click Templates "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/documents/templates.js"
    click RagIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/rag/index.js"
    click RagConsts "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/rag/constants.js"
    click EvalIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/eval/index.js"
    click Metrics "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/eval/metrics.js"
    click Reporters "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/eval/reporters.js"
    click FTIndex "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/finetune/index.js"
    click Schema "https://github.com/sebuzdugan/frai/blob/main/packages/frai-core/src/finetune/schema.js"

    %% Styles
    classDef package fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef module fill:#d4edda,stroke:#333,stroke-width:1px
    classDef fs fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
```
