# dark-athena/plsqlrewrite4gaussdb-web architecture

> Architecture diagram of the GitHub repository dark-athena/plsqlrewrite4gaussdb-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dark-athena/plsqlrewrite4gaussdb-web
- Repository: https://github.com/dark-athena/plsqlrewrite4gaussdb-web

## Overview

1. **Repository shape**
   - This is a three-layer product: a **standalone PL/SQL conversion engine**, a **Spring Boot web backend**, and a **Vue 3 frontend**.
   - The root Maven setup and scripts suggest the same converter is reused both for **CLI/batch use** and for the **web UI**.

2. **Core conversion engine (`src/`)**
   - The heart of the repo is `com.plsqlrewriter.core.PlSqlRewriter`.
   - It uses **ANTLR4-generated PL/SQL parsing** (`src/main/resources/antlr4`, parser base classes in `src/main/java/com/plsqlrewriter/parser/antlr`) to read Oracle PL/SQL and rewrite it for GaussDB.
   - Supporting utilities include batch processing, custom parse error handling, and tree viewing/debugging.

3. **Rule/config-driven transformation layer**
   - Conversion behavior is heavily driven by external files in `config/`.
   - These include datatype, token, exception, identifier, function, query-block, and regex-based mappings.
   - The architecture is intentionally configurable: the parser produces structure, then rule files determine how nodes and tokens are rewritten.

4. **CLI and offline conversion boundary**
   - The root scripts (`convert.sh`, `batch_convert.sh`, `build_core_offline.sh`, etc.) show the core can run **without the web stack**.
   - That makes the converter a reusable library/CLI tool for single-file and directory batch conversion.

5. **Web backend (`webapp/`)**
   - The backend is a separate **Spring Boot 3** application exposing REST endpoints.
   - Controllers are split by domain: auth, users, groups, projects, parameter templates, and SQL rewrite.
   - `SpaForwardController` indicates the backend also serves the frontend SPA entrypoint.

6. **Backend service and persistence model**
   - Business logic lives in `service/`, with repositories in `repository/` and domain entities in `model/`.
   - The main persisted concepts are **User**, **UserGroup**, **Project**, and **ParamTemplate**.
   - This is the management layer for organizing conversion jobs and reusable conversion settings.

7. **Security and bootstrap flow**
   - Authentication is handled by Spring Security via `MySecurityConfig` and `UserDetailsServiceImpl`.
   - `DataInitializer` seeds initial data, including the default admin account referenced in the README.
   - So the web app has a clear login-first boundary before project and conversion operations.

8. **File/package handling for project conversion**
   - The backend includes `TarUtil` and `ZipUtil`, which indicates projects can ingest compressed input sets.
   - Project-level conversion likely flows from uploaded archive/files → unpacking → rewrite engine → stored results for comparison or download.

9. **Frontend SPA (`frontend/`)**
   - The UI is a **Vue 3 + Vite** single-page app.
   - It talks to the backend through API modules in `src/api/` and uses route-based views for login, project list/create, group/user management, and SQL rewrite.
   - The frontend is a client-only layer; the backend serves data and handles all rewrite operations.

10. **Tests, samples, and release/deployment**
   - Core rewrite correctness is validated under `src/test/resources/sql_tests` with input/expected/output fixtures and comparison scripts.
   - Web controllers also have dedicated tests in `webapp/src/test`.
   - Release artifacts are packaged via Maven, Docker, and GitHub Actions workflows, so deployment is supported both as a containerized web app and as offline conversion bundles.

Main entry points: [`webapp/src/main/java/com/plsqlrewriter/webapp/WebappApplication.java`](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/WebappApplication.java) (Spring Boot app), [`src/main/java/com/plsqlrewriter/core/PlSqlRewriter.java`](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/core/PlSqlRewriter.java) (PL/SQL Rewriter), [`frontend/src/api/request.js`](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/frontend/src/api/request.js) (API client), [`webapp/src/main/java/com/plsqlrewriter/webapp/controller/ProjectController.java`](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/ProjectController.java) (Project API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Engine"]
  node_rewriter["PL/SQL Rewriter<br/>rewrite engine<br/>[PlSqlRewriter.java]"]
  node_parser["ANTLR parser<br/>parse layer<br/>[PlSqlParser.g4]"]
  node_rules["Rule configs<br/>mapping rules<br/>[config.properties]"]
  node_batch["Batch tools<br/>file pipeline"]
  node_errors["Error handling<br/>parse support"]
  node_viewer["Tree viewer<br/>debug tool"]
end

subgraph group_web["Web Backend"]
  node_webapp["Spring Boot app<br/>api host"]
  node_security["Security<br/>auth layer"]
  node_authctl["Auth API<br/>controller"]
  node_projectctl["Project API<br/>controller"]
  node_sqlctl["SQL rewrite API<br/>controller"]
  node_userctl["User API<br/>controller"]
  node_groupctl["Group API<br/>controller"]
  node_templctl["Template API<br/>controller"]
  node_domain[("Domain model<br/>entities<br/>[Project.java]")]
  node_repos["Repositories<br/>persistence"]
  node_services["Services<br/>business logic"]
  node_archive["Archive utils<br/>ingest utils<br/>[ZipUtil.java]"]
  node_init["Data init<br/>bootstrap"]
end

subgraph group_ui["Frontend"]
  node_spa["Vue SPA<br/>client app<br/>[main.js]"]
  node_api["API client<br/>frontend api<br/>[request.js]"]
  node_views["Route views<br/>screens<br/>[Login.vue]"]
end

node_pom["Maven build<br/>build root<br/>[pom.xml]"]
node_scripts["CLI scripts<br/>offline entry<br/>[convert.sh]"]

node_pom -->|"builds"| node_rewriter
node_pom -->|"builds"| node_webapp
node_scripts -->|"runs"| node_rewriter
node_scripts -->|"batch"| node_batch
node_rewriter -->|"parses via"| node_parser
node_rewriter -->|"applies"| node_rules
node_rewriter -->|"reports"| node_errors
node_rewriter -->|"inspects"| node_viewer
node_batch -->|"orchestrates"| node_rewriter
node_webapp -->|"protects"| node_security
node_webapp -->|"hosts"| node_authctl
node_webapp -->|"hosts"| node_projectctl
node_webapp -->|"hosts"| node_sqlctl
node_webapp -->|"hosts"| node_userctl
node_webapp -->|"hosts"| node_groupctl
node_webapp -->|"hosts"| node_templctl
node_projectctl -->|"delegates"| node_services
node_sqlctl -->|"uses"| node_rewriter
node_services -->|"persists via"| node_repos
node_repos -->|"stores"| node_domain
node_projectctl -->|"ingests"| node_archive
node_init -->|"seeds"| node_domain
node_spa -->|"calls"| node_api
node_api -->|"requests"| node_authctl
node_api -->|"requests"| node_projectctl
node_api -->|"requests"| node_sqlctl
node_views -->|"rendered in"| node_spa

click node_pom "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/pom.xml"
click node_scripts "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/convert.sh"
click node_rewriter "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/core/PlSqlRewriter.java"
click node_parser "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/resources/antlr4/PlSqlParser.g4"
click node_rules "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/config/config.properties"
click node_batch "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/util/BatchProcessor.java"
click node_errors "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/util/CustomErrorListener.java"
click node_viewer "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/util/PlSqlTreeViewer.java"
click node_webapp "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/WebappApplication.java"
click node_security "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/security/MySecurityConfig.java"
click node_authctl "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/AuthController.java"
click node_projectctl "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/ProjectController.java"
click node_sqlctl "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/SqlRewriteController.java"
click node_userctl "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserController.java"
click node_groupctl "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserGroupController.java"
click node_templctl "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/ParamTemplateController.java"
click node_domain "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/model/Project.java"
click node_repos "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/repository/ProjectRepository.java"
click node_services "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/service/ProjectService.java"
click node_archive "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/util/ZipUtil.java"
click node_init "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/DataInitializer.java"
click node_spa "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/frontend/src/main.js"
click node_api "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/frontend/src/api/request.js"
click node_views "https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/frontend/src/views/Login.vue"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rewriter,node_parser,node_rules,node_batch,node_errors,node_viewer toneBlue
class node_webapp,node_security,node_authctl,node_projectctl,node_sqlctl,node_userctl,node_groupctl,node_templctl,node_domain,node_repos,node_services,node_archive,node_init toneAmber
class node_spa,node_api,node_views toneMint
class node_pom,node_scripts toneNeutral
```

## Components

### Core Engine

Standalone PL/SQL rewrite engine, parser, and rule-driven transformation layer.

- [PL/SQL Rewriter](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/core/PlSqlRewriter.java): rewrite engine · Main conversion engine that rewrites Oracle PL/SQL toward GaussDB. · `src/main/java/com/plsqlrewriter/core/PlSqlRewriter.java`
- [ANTLR parser](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/resources/antlr4/PlSqlParser.g4): parse layer · Generated lexer/parser base classes and grammar-backed parsing support. · `src/main/resources/antlr4/PlSqlParser.g4`
- [Rule configs](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/config/config.properties): mapping rules · External mappings and patterns that drive token, datatype, function, and query rewrites. · `config/config.properties`
- [Batch tools](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/util/BatchProcessor.java): file pipeline · Directory/file batch processing for offline conversion runs. · `src/main/java/com/plsqlrewriter/util/BatchProcessor.java`
- [Error handling](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/util/CustomErrorListener.java): parse support · Custom parse error listener for recovery and diagnostics. · `src/main/java/com/plsqlrewriter/util/CustomErrorListener.java`
- [Tree viewer](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/src/main/java/com/plsqlrewriter/util/PlSqlTreeViewer.java): debug tool · Parse-tree inspection and debugging support for conversion development. · `src/main/java/com/plsqlrewriter/util/PlSqlTreeViewer.java`

### Web Backend

Spring Boot API, security, persistence, and project orchestration.

- [Spring Boot app](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/WebappApplication.java): api host · Backend application that exposes rewrite and management APIs. · `webapp/src/main/java/com/plsqlrewriter/webapp/WebappApplication.java`
- [Security](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/security/MySecurityConfig.java): auth layer · Spring Security configuration and user-details integration. · `webapp/src/main/java/com/plsqlrewriter/webapp/security/MySecurityConfig.java`
- [Auth API](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/AuthController.java): controller · Login and authentication endpoints. · `webapp/src/main/java/com/plsqlrewriter/webapp/controller/AuthController.java`
- [Project API](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/ProjectController.java): controller · Project lifecycle and conversion job endpoints. · `webapp/src/main/java/com/plsqlrewriter/webapp/controller/ProjectController.java`
- [SQL rewrite API](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/SqlRewriteController.java): controller · Direct SQL rewrite endpoint backed by the shared engine. · `webapp/src/main/java/com/plsqlrewriter/webapp/controller/SqlRewriteController.java`
- [User API](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserController.java): controller · User management endpoints. · `webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserController.java`
- [Group API](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserGroupController.java): controller · User-group management endpoints. · `webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserGroupController.java`
- [Template API](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/controller/ParamTemplateController.java): controller · Parameter template management endpoints. · `webapp/src/main/java/com/plsqlrewriter/webapp/controller/ParamTemplateController.java`
- [Domain model](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/model/Project.java): entities · Persisted users, groups, projects, and parameter templates. · `webapp/src/main/java/com/plsqlrewriter/webapp/model/Project.java`
- [Repositories](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/repository/ProjectRepository.java): persistence · Spring Data repositories for backend entities. · `webapp/src/main/java/com/plsqlrewriter/webapp/repository/ProjectRepository.java`
- [Services](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/service/ProjectService.java): business logic · Backend service layer coordinating persistence and conversion flows. · `webapp/src/main/java/com/plsqlrewriter/webapp/service/ProjectService.java`
- [Archive utils](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/util/ZipUtil.java): ingest utils · Tar and zip extraction for project input sets. · `webapp/src/main/java/com/plsqlrewriter/webapp/util/ZipUtil.java`
- [Data init](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/webapp/src/main/java/com/plsqlrewriter/webapp/DataInitializer.java): bootstrap · Seeds default application data, including initial admin setup. · `webapp/src/main/java/com/plsqlrewriter/webapp/DataInitializer.java`

### Frontend

Vue 3 single-page application that consumes backend APIs.

- [Vue SPA](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/frontend/src/main.js): client app · Vue 3 + Vite single-page frontend. · `frontend/src/main.js`
- [API client](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/frontend/src/api/request.js): frontend api · Browser-side request modules for auth, users, groups, projects, and SQL rewrite. · `frontend/src/api/request.js`
- [Route views](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/frontend/src/views/Login.vue): screens · Login, project, user, group, and rewrite screens. · `frontend/src/views/Login.vue`

### Other components

- [Maven build](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/pom.xml): build root · Top-level Maven packaging for the shared engine and web app. · `pom.xml`
- [CLI scripts](https://github.com/dark-athena/plsqlrewrite4gaussdb-web/blob/master/convert.sh): offline entry · Shell/batch entrypoints for standalone conversion and server startup. · `convert.sh`

## Connections

- Maven build → PL/SQL Rewriter: builds · Root build packages the shared conversion engine.
- Maven build → Spring Boot app: builds · Root build also packages the web application.
- CLI scripts → PL/SQL Rewriter: runs · Offline scripts invoke the standalone converter.
- CLI scripts → Batch tools: batch · Batch scripts drive directory-scale conversions.
- PL/SQL Rewriter → ANTLR parser: parses via · The rewrite engine consumes ANTLR grammar output.
- PL/SQL Rewriter → Rule configs: applies · Transformation behavior is driven by external mapping files.
- PL/SQL Rewriter → Error handling: reports · Parsing and rewrite failures go through custom listeners.
- PL/SQL Rewriter → Tree viewer: inspects · Tree viewer supports debugging and analysis of parse trees.
- Batch tools → PL/SQL Rewriter: orchestrates · Batch processing coordinates repeated rewrite runs.
- Spring Boot app → Security: protects · Backend application is guarded by Spring Security.
- Spring Boot app → Auth API: hosts · Application exposes authentication endpoints.
- Spring Boot app → Project API: hosts · Application exposes project and conversion endpoints.
- Spring Boot app → SQL rewrite API: hosts · Application exposes direct rewrite endpoints.
- Spring Boot app → User API: hosts · Application exposes user-management endpoints.
- Spring Boot app → Group API: hosts · Application exposes group-management endpoints.
- Spring Boot app → Template API: hosts · Application exposes template-management endpoints.
- Project API → Services: delegates · Controllers delegate business logic to services.
- SQL rewrite API → PL/SQL Rewriter: uses · SQL rewrite API reuses the shared conversion engine.
- Services → Repositories: persists via · Service layer talks to repositories for domain state.
- Repositories → Domain model: stores · Repositories map the persisted entities.
- Project API → Archive utils: ingests · Project flows can unpack tar/zip inputs before rewrite.
- Data init → Domain model: seeds · Bootstrap data populates core entities and defaults.
- Vue SPA → API client: calls · Frontend screens use browser API modules.
- API client → Auth API: requests · Client sends authentication requests to backend.
- API client → Project API: requests · Client manages project operations through the API.
- API client → SQL rewrite API: requests · Client submits rewrite jobs through the API.
- Route views → Vue SPA: rendered in · Views compose the main SPA routes and screens.
