# tencent/apijson architecture

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

- Interactive diagram: https://gitdiagram.com/tencent/apijson
- Repository: https://github.com/tencent/apijson

## Overview

##### Project type and purpose
- This is a back-end Java library (no UI) that implements a JSON‐protocol API → SQL translation engine.
- It parses incoming JSON requests (CRUD, joins, nested queries), auto-generates SQL, executes via JDBC, and returns JSON.

##### File structure
- Top-level “APIJSONORM” Maven module with pom.xml → core Java library.
- src/main/java/apijson contains protocol classes: JSON, JSONParser, JSONRequest, JSONResponse, Log, StringUtil, etc.
- src/main/java/apijson/orm contains the heart of the SQL engine: AbstractParser hierarchy, ParserCreator, FunctionParser, ObjectParser, SQLConfig, SQLCreator, SQLExecutor, Verifier, VerifierCreator, Exception classes, plus model and script subpackages.
- src/main/resources/application.properties for default config.

##### Extract key internal components
a. HTTP/Framework Launcher (provided by user’s SpringBoot or JFinal integration – not in this module): receives HTTP JSON payload.
b. JSON Layer
– JSONRequest: wraps raw JSON → internal Java objects
– JSONParser / ParserCreator: picks the right parser (FunctionParser vs. ObjectParser)
c. Parser Layer
– AbstractParser → FunctionParser / ObjectParser → builds an internal representation of operations (Entry objects, Pair, Join, Logic).
– Verifier (from VerifierCreator): enforces schema/permission rules.
d. SQL Layer
– SQLConfig: contains DB metadata, table/column mappings.
– SQLCreator: constructs SQL strings from parsed representations.
– AbstractSQLExecutor / SQLExecutor: executes SQL via JDBC, returns raw ResultSets.
e. Response Layer
– JSONCreator / JSONResponse: transforms ResultSets back into JSONList/JSONMap structures.
f. Extension Points
– ScriptExecutor (JavaScriptExecutor, JSR223ScriptExecutor) for remote functions.
– OnParseCallback hooks, custom VerifierCreator, custom SQLExecutorCreator.

##### Relationships and data flow
1. HTTP Request → JSONRequest
2. JSONRequest → ParserCreator → JSONParser / AbstractParser
3. AbstractParser → Verifier → (passes or errors)
4. AbstractParser → SQLConfig + SQLCreator → SQL string
5. SQL string → SQLExecutor → JDBC → Database
6. ResultSet → JSONCreator → JSONResponse
7. JSONResponse → HTTP Response

##### Architectural patterns & principles
- Factory/Creator (ParserCreator, VerifierCreator, SQLExecutorCreator)
- Template Method (AbstractParser, AbstractSQLExecutor)
- Strategy (multiple Parser and Verifier implementations)
- Visitor (Visitor interface for walking parse trees)
- Layered separation (Protocol, Parse, SQL, Execute, Response)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Layer
    subgraph "HTTP & JSON Layer"
        direction TB
        Framework["Framework (SpringBoot/JFinal)"]:::entryExit
        JSONRequest["JSONRequest"]:::core
        JSONParser["JSONParser"]:::core
        JSON["JSON"]:::core
        JSONList["JSONList"]:::core
        JSONMap["JSONMap"]:::core
        JSONResponse["JSONResponse"]:::core
    end

    %% Parser & Verifier Layer
    subgraph "Parser & Verifier Layer"
        direction TB
        ParserCreator["ParserCreator"]:::core
        AbstractParser["AbstractParser"]:::core
        FunctionParser["FunctionParser"]:::core
        ObjectParser["ObjectParser"]:::core
        VerifierCreator["VerifierCreator"]:::core
        Verifier["Verifier"]:::core
    end

    %% SQL Layer
    subgraph "SQL Layer"
        direction TB
        SQLConfig["SQLConfig"]:::core
        AbstractSQLConfig["AbstractSQLConfig"]:::core
        SQLCreator["SQLCreator"]:::core
        SQLHelper["SQL"]:::core
    end

    %% Execution Layer
    subgraph "Execution Layer"
        direction TB
        AbstractSQLExecutor["AbstractSQLExecutor"]:::core
        SQLExecutor["SQLExecutor"]:::core
        JDBC["JDBC"]:::entryExit
    end

    %% Response Layer
    subgraph "Response Layer"
        direction TB
        JSONCreator["JSONCreator"]:::core
        JSONResponse2["JSONResponse"]:::core
    end

    %% Database
    Database["Database"]:::entryExit

    %% Extension Points
    subgraph "Extension Points"
        direction TB
        ScriptExecutor["ScriptExecutor"]:::extension
        JavaScriptExecutor["JavaScriptExecutor"]:::extension
        JSR223ScriptExecutor["JSR223ScriptExecutor"]:::extension
        OnParseCallback["OnParseCallback"]:::extension
    end

    %% Data Flow
    Framework -->|receives JSON| JSONRequest
    JSONRequest --> JSONParser
    JSONParser -->|creates| ParserCreator
    ParserCreator --> AbstractParser
    AbstractParser --> FunctionParser
    AbstractParser --> ObjectParser
    AbstractParser --> VerifierCreator
    VerifierCreator --> Verifier
    Verifier -->|validated| AbstractParser
    AbstractParser --> SQLConfig
    AbstractParser --> SQLCreator
    SQLConfig --> SQLCreator
    SQLCreator --> SQLHelper
    SQLCreator --> AbstractSQLExecutor
    AbstractSQLExecutor --> SQLExecutor
    SQLExecutor --> JDBC
    JDBC --> Database
    Database --> JSONCreator
    JSONCreator --> JSONResponse2
    JSONResponse2 -->|returns JSON| Framework

    %% Extension flows
    AbstractParser -.->|onParse| OnParseCallback
    AbstractParser -.->|script| ScriptExecutor
    ScriptExecutor --> JavaScriptExecutor
    ScriptExecutor --> JSR223ScriptExecutor

    %% Click Events
    click JSONRequest "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/JSONRequest.java"
    click JSONParser "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/JSONParser.java"
    click JSONResponse "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/JSONResponse.java"
    click JSON "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/JSON.java"
    click JSONList "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/JSONList.java"
    click JSONMap "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/JSONMap.java"
    click AbstractParser "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/AbstractParser.java"
    click AbstractFunctionParser "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/AbstractFunctionParser.java"
    click AbstractObjectParser "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java"
    click FunctionParser "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/FunctionParser.java"
    click ObjectParser "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/ObjectParser.java"
    click ParserCreator "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/ParserCreator.java"
    click Entry "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/Entry.java"
    click Pair "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/Pair.java"
    click Join "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/Join.java"
    click Logic "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/Logic.java"
    click AbstractVerifier "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java"
    click Verifier "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/Verifier.java"
    click VerifierCreator "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/VerifierCreator.java"
    click SQLConfig "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/SQLConfig.java"
    click AbstractSQLConfig "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java"
    click SQLCreator "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/SQLCreator.java"
    click SQLHelper "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/SQL.java"
    click AbstractSQLExecutor "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java"
    click SQLExecutor "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/SQLExecutor.java"
    click JSONCreator "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/JSONCreator.java"
    click ScriptExecutor "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/script/ScriptExecutor.java"
    click JavaScriptExecutor "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/script/JavaScriptExecutor.java"
    click JSR223ScriptExecutor "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/script/JSR223ScriptExecutor.java"
    click OnParseCallback "https://github.com/tencent/apijson/blob/master/APIJSONORM/src/main/java/apijson/orm/OnParseCallback.java"

    %% Styles
    classDef entryExit fill:#ccffcc,stroke:#006600,color:#000000
    classDef core fill:#cce5ff,stroke:#004085,color:#000000
    classDef extension fill:#e2ccff,stroke:#6f42c1,color:#000000
```
