# nanoapi-io/napi architecture

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

- Interactive diagram: https://gitdiagram.com/nanoapi-io/napi
- Repository: https://github.com/nanoapi-io/napi

## Overview

##### Project type and purpose
- Type: A CLI‐driven “analysis & refactoring” application library (a modular monolith) with plugin support for multiple languages.
- Purpose:
- Provide commands (manifest generate, extract, etc.) that parse code, build an architectural manifest, extract symbols, and push data to a NanoAPI backend.

##### File structure
- Top‐level “src” modules:
- **cli/** – CLI entrypoint, handlers, and middlewares
- **apiService/** – HTTP client for remote NanoAPI backend
- **helpers/** – Common utilities (filesystem, source‐code parsing, tree‐sitter integration)
- **languagePlugins/** – One subfolder per language (c, csharp, java, python), each containing extractor, resolver, metrics, etc.
- **symbolExtractor/** – Cross‐language symbol‐extraction orchestration
- **manifest/** – Dependency‐manifest generator (language‐specific and generic)
- Support directories:
- **examples/** – Sample projects in different languages demonstrating usage
- **scripts/** – Utility scripts (versioning, Python stdlib list generation)
- **install_scripts/** – OS‐specific install entrypoints
- CI/CD:
- **.github/workflows/** – Lint, test, compile, and release pipelines

##### README for additional insights
- Core features: audit, refactor, build, integrate, live‐view architecture
- Stresses deterministic, open‐source approach, CI/CD compatibility, and plugin extensibility
- Mentions a separate UI (not part of this repo) that reads the manifest pushed by the CLI

##### Core components & interactions
1. CLI Layer
- Command parser
- Handlers (login, init, manifest, extract, etc.)
- Middlewares (auth check, config load, version check)
2. Core Services
- Manifest Generator (generic + language‐specific)
- Symbol Extractor
- Helpers (filesystem, tree‐sitter)
3. Language Plugins (for each supported language)
- Extractor, Resolver, Metrics, Dependency Formatter, Symbol Registry, etc.
4. API Client (apiService)
- HTTP/REST calls to NanoAPI backend
- Auth token management
5. External NanoAPI Backend (cloud service + UI)
- Authentication service
- Manifest storage & indexing
- UI & visualizer
6. CI/CD Pipeline (GitHub Actions)
- Lint, test, build, and release workflows

1. User → CLI Layer (issues commands)
2. CLI Layer → Core Services (invoke manifest generator or extractor)
3. Core Services ↔ Helpers (filesystem reads, Tree-sitter parse calls)
4. Core Services → Language Plugins (pass ASTs or source trees; receive symbols, metrics, dependency info)
5. Core Services → API Client (package up manifest or extraction payload)
6. API Client → NanoAPI Backend (push data; receive acknowledgments)
7. CI/CD → CLI Layer & Tests (automated on push/pull request)

c. Architectural Patterns & Principles
- **Layered Architecture**: Separation between presentation (CLI), application logic (core services), domain (language plugins), and infrastructure (helpers, API client).
- **Plugin Architecture**: Each language support lives in a self-contained module under `languagePlugins/`, enabling easy extension.
- **Middleware Pattern**: CLI processing chain applies cross-cutting concerns (config loading, auth validation) before invoking handlers.
- **Adapter/Facade**: `apiService` abstracts HTTP details from core logic.
- **Test‐Driven**: Each module has corresponding `.test.ts` verifying functionality.

d. Key Technologies & Frameworks
- TypeScript/Node (Deno compatibility via `deno.json`)
- Tree-sitter for parsing multiple languages
- REST over HTTPS for backend communication
- GitHub Actions for CI/CD
- Shell scripts for installation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "CLI Layer"
        direction TB
        CLI_Index["Entry Point\nsrc/cli/index.ts"]:::cli
        CLI_Handlers["Handlers\nsrc/cli/handlers/"]:::cli
        CLI_Middleware["Middlewares\nsrc/cli/middlewares/"]:::cli
    end

    %% Core Services & Helpers
    subgraph "Core Services & Helpers"
        direction TB
        subgraph "Core Services"
            direction TB
            ManifestGen["Manifest Generator"]:::core
            SymbolExt["Symbol Extractor"]:::core
        end
        subgraph "Helpers"
            direction TB
            FSHelpers["FileSystem Helpers\nsrc/helpers/fileSystem/index.ts"]:::infra
            SCParsing["SourceCode Parsing\nsrc/helpers/sourceCode/index.ts"]:::infra
            SCParsingTest["SourceCode Tests\nsrc/helpers/sourceCode/index.test.ts"]:::infra
            TSitter["Tree-sitter Parsers\nsrc/helpers/treeSitter/parsers.ts"]:::infra
        end
    end

    %% Manifest Generator modules
    subgraph "Dependency Manifest Modules"
        direction TB
        ManifestGeneric["Generic Manifest\nsrc/manifest/dependencyManifest/index.ts"]:::manifest
        ManifestC["C Manifest\nsrc/manifest/dependencyManifest/c/index.ts"]:::manifest
        ManifestCSharp["CSharp Manifest\nsrc/manifest/dependencyManifest/csharp/index.ts"]:::manifest
        ManifestJava["Java Manifest\nsrc/manifest/dependencyManifest/java/index.ts"]:::manifest
        ManifestPython["Python Manifest\nsrc/manifest/dependencyManifest/python/index.ts"]:::manifest
        ManifestTypes["Manifest Types\nsrc/manifest/dependencyManifest/types.ts"]:::manifest
    end

    %% Symbol Extractor modules
    subgraph "Symbol Extractor Modules"
        direction TB
        SymCore["Core Orchestrator\nsrc/symbolExtractor/index.ts"]:::symbol
        SymTypes["Types\nsrc/symbolExtractor/types.ts"]:::symbol
        SymC["C Plugin\nsrc/symbolExtractor/c/index.ts"]:::symbol
        SymCSharp["CSharp Plugin\nsrc/symbolExtractor/csharp/index.ts"]:::symbol
        SymJava["Java Plugin\nsrc/symbolExtractor/java/index.ts"]:::symbol
        SymPython["Python Plugin\nsrc/symbolExtractor/python/index.ts"]:::symbol
    end

    %% Language Plugins
    subgraph "Language Plugins"
        direction TB
        CPlugin["C Plugin\nsrc/languagePlugins/c/"]:::plugin
        CSharpPlugin["CSharp Plugin\nsrc/languagePlugins/csharp/"]:::plugin
        JavaPlugin["Java Plugin\nsrc/languagePlugins/java/"]:::plugin
        PythonPlugin["Python Plugin\nsrc/languagePlugins/python/"]:::plugin
    end

    %% API Client
    APIClient["API Client\nsrc/apiService/index.ts"]:::api

    %% External NanoAPI Backend & UI
    ExternalCloud["NanoAPI Backend & UI"]:::external

    %% CI/CD Pipelines
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        LintTestCompile["Lint/Test/Compile Workflow\n.github/workflows/lint_test_compile.yml"]:::cicd
        ReleaseWorkflow["Release Workflow\n.github/workflows/release.yml"]:::cicd
    end

    %% Data Flow
    User["User"]:::user
    User -->|"issues commands"| CLI_Index
    CLI_Index -->|"parse & route"| ManifestGen
    CLI_Index -->|"parse & route"| SymbolExt
    CLI_Index -->|"via middlewares"| CLI_Middleware
    ManifestGen -->|"uses"| FSHelpers
    ManifestGen -->|"uses"| SCParsing
    ManifestGen -->|"uses"| TSitter
    SymbolExt -->|"uses"| FSHelpers
    SymbolExt -->|"uses"| SCParsing
    SymbolExt -->|"uses"| TSitter
    ManifestGen -->|"invokes"| ManifestGeneric
    ManifestGen -->|"invokes"| ManifestC
    ManifestGen -->|"invokes"| ManifestCSharp
    ManifestGen -->|"invokes"| ManifestJava
    ManifestGen -->|"invokes"| ManifestPython
    SymbolExt -->|"invokes"| SymCore
    SymCore -->|"loads"| SymC
    SymCore -->|"loads"| SymCSharp
    SymCore -->|"loads"| SymJava
    SymCore -->|"loads"| SymPython
    ManifestGen -->|"packages manifest"| APIClient
    SymbolExt -->|"packages symbols"| APIClient
    APIClient -->|"POST /manifest"| ExternalCloud
    ExternalCloud -->|"acknowledgment"| APIClient
    LintTestCompile -->|"runs on push/PR"| CLI_Index
    LintTestCompile -->|"tests core & plugins"| ManifestGen
    LintTestCompile -->|"tests core & plugins"| SymbolExt
    ReleaseWorkflow -->|"publishes releases"| CLI_Index

    %% Click Events
    click CLI_Index "https://github.com/nanoapi-io/napi/blob/main/src/cli/index.ts"
    click CLI_Handlers "https://github.com/nanoapi-io/napi/tree/main/src/cli/handlers/"
    click CLI_Middleware "https://github.com/nanoapi-io/napi/tree/main/src/cli/middlewares/"
    click FSHelpers "https://github.com/nanoapi-io/napi/blob/main/src/helpers/fileSystem/index.ts"
    click SCParsing "https://github.com/nanoapi-io/napi/blob/main/src/helpers/sourceCode/index.ts"
    click SCParsingTest "https://github.com/nanoapi-io/napi/blob/main/src/helpers/sourceCode/index.test.ts"
    click TSitter "https://github.com/nanoapi-io/napi/blob/main/src/helpers/treeSitter/parsers.ts"
    click ManifestGeneric "https://github.com/nanoapi-io/napi/blob/main/src/manifest/dependencyManifest/index.ts"
    click ManifestC "https://github.com/nanoapi-io/napi/blob/main/src/manifest/dependencyManifest/c/index.ts"
    click ManifestCSharp "https://github.com/nanoapi-io/napi/blob/main/src/manifest/dependencyManifest/csharp/index.ts"
    click ManifestJava "https://github.com/nanoapi-io/napi/blob/main/src/manifest/dependencyManifest/java/index.ts"
    click ManifestPython "https://github.com/nanoapi-io/napi/blob/main/src/manifest/dependencyManifest/python/index.ts"
    click ManifestTypes "https://github.com/nanoapi-io/napi/blob/main/src/manifest/dependencyManifest/types.ts"
    click SymCore "https://github.com/nanoapi-io/napi/blob/main/src/symbolExtractor/index.ts"
    click SymTypes "https://github.com/nanoapi-io/napi/blob/main/src/symbolExtractor/types.ts"
    click SymC "https://github.com/nanoapi-io/napi/blob/main/src/symbolExtractor/c/index.ts"
    click SymCSharp "https://github.com/nanoapi-io/napi/blob/main/src/symbolExtractor/csharp/index.ts"
    click SymJava "https://github.com/nanoapi-io/napi/blob/main/src/symbolExtractor/java/index.ts"
    click SymPython "https://github.com/nanoapi-io/napi/blob/main/src/symbolExtractor/python/index.ts"
    click CPlugin "https://github.com/nanoapi-io/napi/tree/main/src/languagePlugins/c/"
    click CSharpPlugin "https://github.com/nanoapi-io/napi/tree/main/src/languagePlugins/csharp/"
    click JavaPlugin "https://github.com/nanoapi-io/napi/tree/main/src/languagePlugins/java/"
    click PythonPlugin "https://github.com/nanoapi-io/napi/tree/main/src/languagePlugins/python/"
    click APIClient "https://github.com/nanoapi-io/napi/blob/main/src/apiService/index.ts"
    click LintTestCompile "https://github.com/nanoapi-io/napi/blob/main/.github/workflows/lint_test_compile.yml"
    click ReleaseWorkflow "https://github.com/nanoapi-io/napi/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#3399ff;
    classDef core fill:#d4edda,stroke:#28a745;
    classDef infra fill:#e2e3e5,stroke:#6c757d;
    classDef manifest fill:#fff3cd,stroke:#ffcd39;
    classDef symbol fill:#fff3cd,stroke:#e0a800;
    classDef plugin fill:#fff8e1,stroke:#ffca28;
    classDef api fill:#ffe5b4,stroke:#ff8c00;
    classDef external fill:#f0f0f0,stroke:#888888;
    classDef cicd fill:#f3e5f5,stroke:#9c27b0;
    classDef user fill:#ffffff,stroke:#000000;
    classDef symbol,manifest subgraphLabel
    classDef external cloud
    class User user
```
