• Application Workbench (Git Integration)
  • Overview & Architecture
    • How Repository & Database Relationships Are Recorded
  • Enabling the Feature
    • Step 1: Enable the API Server Feature Flag & Configure Workspace Storage
      • How Repository Workspaces Work
      • Option A: Local Development (start-local.sh or api-server/.env)
      • Option B: Container Deployment (docker-compose.yaml)
    • Step 2: Configure Git Authentication & Credentials
    • Step 3: Enable the Frontend Feature Flag & Build UI
  • Technical Workflows
    • 1. Repository Discovery, Cloning & Pulling
    • 2. Branch Viewing & Switching
    • 3. Dependency Indexing (.visulate/<db>/oracle-code-map.json & .visulate/<db>/codebase-dependencies.md)
    • 4. Bi-Directional Database-to-Code Navigation
    • 5. AI Agent & MCP Server Integration
    • 6. File Editing, Diffs, and Committing
  • API Reference Summary

Application Workbench (Git Integration)

The Application Workbench connects Visulate’s database metadata catalog with your application source code repositories. It provides an embedded Monaco Editor environment, bi-directional database-to-code navigation, automated dependency indexing, Git version control workflows, and integrated AI-assisted modernizations.

Overview & Architecture

Modern database-centric applications frequently suffer from a disconnect between the database data dictionary (tables, views, packages, procedures) and the application codebases that consume them.

The Application Workbench bridges this gap:

                                  BROWSER (Angular UI)
                     +----------------------------------------------------+
                     | - Session Auth Dialog:                             |
                     |     * Personal Access Token (HTTPS PAT)            |
                     |     * Author Name & Email                          |
                     | - Stored in sessionStorage (cleared on close)      |
                     | - HTTP Interceptor attaches headers:               |
                     |     X-Git-User: <username>                         |
                     |     X-Git-Token: <token>                           |
                     |     X-Git-Author-Name: <name>                      |
                     |     X-Git-Author-Email: <email>                    |
                     +-------------------------+--------------------------+
                                               |
                                     HTTP REST |
                                               v
                                 VISULATE API SERVER (Node.js)
                     +----------------------------------------------------+
                     | Git Middleware & Service:                          |
                     |  - Resolves workspace directory:                   |
                     |      Local mode:  $GIT_REPOS_DIR                   |
                     |      Server mode: $GIT_REPOS_DIR/users/:user/      |
                     |  - Executes Git operations dynamically:            |
                     |      * HTTPS: token injected via http.extraHeader  |
                     |      * Commit: -c user.name="..." -c user.email    |
                     |      * Pull / Push: applies active session auth    |
                     |  - MCP Server & AI Integration:                    |
                     |      * Injects codebase dependencies in getContext |
                     |      * Exposes getCodebaseDependencies MCP tool    |
                     +-------------------------+--------------------------+
                                               |
                                               v
                      +----------------------------------------------------+
                      | Workspace Storage Directory / Mount                |
                      |  Container: /app/repos/<project>/                  |
                      |  Host bind: /home/visulate/repos/<project>/        |
                      |  Local dev: $HOME/git/<project>/                   |
                      |  - .visulate/<db>/oracle-code-map.json             |
                      |  - .visulate/<db>/codebase-dependencies.md         |
                      +----------------------------------------------------+

How Repository & Database Relationships Are Recorded

Visulate records the relationship between source code repositories and database schemas without mutable server-side registries:

1. Schema Object-to-Code Mapping (.visulate/<db>/oracle-code-map.json): Stored inside the .visulate/<db>/ subdirectory of each repository (where <db> is the database endpoint identifier, e.g. pdb21, dev, uat, prod — with fallback to legacy .okf/<db>/ if present), this file records the associated database connection (dbConnectionId) along with bi-directional mappings between database catalog objects and specific code files:

   {
     "projectId": "visulate",
     "dbConnectionId": "pdb21",
     "indexedAt": "2026-09-07T18:00:00.000Z",
     "objects": {
       "PR_PROPERTIES": {
         "owner": "RNTMGR2",
         "type": "TABLE",
         "files": [
           "code/database/plsql/rnt_properties_pkg.sql",
           "code/php/classes/database/pr_properties.class.php"
         ]
       }
     },
     "files": {
       "code/database/plsql/rnt_properties_pkg.sql": [
         "PR_PROPERTIES",
         "PR_PROPERTY_PHOTOS"
       ]
     }
   }
   

2. Open Knowledge Format (OKF) Architectural Memory (.visulate/<db>/codebase-dependencies.md): In addition to JSON data, the indexer generates a structured Markdown document summarizing mapped database objects, referencing code files, and schema dependencies for each target database environment.
3. Multi-Database Support in a Single Repository: Because a single repository may hold the source for multiple database environments (e.g. Dev, UAT, and Prod), dependencies are stored per-database in .visulate/<db>/, allowing distinct mappings for each database without collision.
4. Dynamic Live Git State: Active branches, remotes, and diffs are queried live from the Git repositories on disk rather than cached in static files.
5. Committed With Code: Because .visulate/<db>/oracle-code-map.json and .visulate/<db>/codebase-dependencies.md live inside the repository, database relationships and entity indexes travel with the Git repository across branches and team checkouts.
6. Browser Storage Association: Users can link any Database and Git Repository directly from the top toolbar using the Link icon button or keyboard shortcut (Alt+L). Associations are maintained in browser localStorage. Once linked, selecting a database automatically selects its associated repository. Clicking the button again breaks the association.

Enabling the Feature

Follow these step-by-step instructions to enable the Application Workbench:

Step 1: Enable the API Server Feature Flag & Configure Workspace Storage

In the backend API server (api-server), set the ENABLE_GIT_INTEGRATION environment variable to true.

How Repository Workspaces Work

Visulate scans the directory configured by GIT_REPOS_DIR (by default /app/repos in Docker or $HOME/git in local development) for Git repositories. Each immediate child directory containing a .git folder is recognized as an available project repository:

/home/visulate/repos/                     <-- Host directory mounted to /app/repos
├── openproject/                          <-- Discovered as repository "openproject"
│   ├── .git/
│   └── ...
└── my-app/                               <-- Discovered as repository "my-app"
    ├── .git/
    └── ...

[!IMPORTANT] Always mount a parent repositories directory into /app/repos. Do not bind mount an individual repository folder directly as /app/repos (e.g. /home/visulate/openproject:/app/repos), because Visulate scans the mounted folder for child directories that are Git repositories.

Option A: Local Development (start-local.sh or api-server/.env)

In local mode, the API server runs directly as your local OS user and points to your real Git directory ($HOME/git) without any nested user subfolders:

export ENABLE_GIT_INTEGRATION=true
export GIT_MODE=local
export GIT_REPOS_DIR="${GIT_REPOS_DIR:-$HOME/git}"

Option B: Container Deployment (docker-compose.yaml)

In a container deployment, use a host bind mount so that repositories cloned on the host machine (or pre-existing repositories) are directly accessible to the containers:

1. Create the parent directory on the host:

   mkdir -p /home/visulate/repos
   chmod -R 775 /home/visulate/repos
   

2. Move or clone project repositories into this directory:

   # Move an existing clone from a personal home directory:
   mv /home/pgoldtho/openproject /home/visulate/repos/openproject
   
   # Or clone directly into the folder:
   git clone https://github.com/opf/openproject.git /home/visulate/repos/openproject
   

3. Configure docker-compose.yaml: Mount the relative ./repos directory into /app/repos for both the visapi service (API server) and ai-agent service (AI agents), with GIT_MODE=local:

   services:
     visapi:
       environment:
         - ENABLE_GIT_INTEGRATION=true
         - GIT_MODE=local
         - GIT_REPOS_DIR=/app/repos
       volumes:
         - ./api-server/config:/visulate-server/config
         - visulate-downloads:/visulate-server/downloads
         - ./repos:/app/repos
         - ./wallet:/opt/oracle/network/admin:ro
   
     ai-agent:
       environment:
         - GOOGLE_AI_KEY=${GOOGLE_AI_KEY}
         - GOOGLE_API_KEY=${GOOGLE_AI_KEY}
         - GIT_REPOS_DIR=/app/repos
         - VISULATE_BASE=http://reverseproxy
       volumes:
         - visulate-downloads:/app/downloads
         - ./repos:/app/repos
         - ./wallet:/opt/oracle/network/admin:ro
   

   (Note: You can also use an absolute path such as /home/visulate/repos:/app/repos if your repositories directory is maintained outside the deployment folder).

[!NOTE] Local Mode vs Server Mode:

• GIT_MODE=local (recommended for standard and container deployments): Repositories reside directly in /app/repos/<project> and are shared across workbench sessions.
• GIT_MODE=server (multi-tenant mode behind an authenticating proxy): Workspaces are partitioned by authenticated username under /app/repos/users/<username>/<project>.

Step 2: Configure Git Authentication & Credentials

Visulate uses Personal Access Tokens (HTTPS) for session-based authentication:

1. Click the Git Auth button in the Workbench toolbar.
2. Enter your Git Username (e.g. your GitHub or GitLab username).
3. Enter your Personal Access Token (PAT) (e.g. GitHub ghp_... or GitLab glpat-...).
4. Enter your Author Name and Author Email for Git commits.
5. Click Save Session Credentials.

Credentials are saved exclusively in the browser’s sessionStorage and are never written to server-side configuration files or Git config. When the user closes the browser tab, the session credentials are automatically destroyed.

Step 3: Enable the Frontend Feature Flag & Build UI

The Angular UI uses the enableGitIntegration flag to activate the Workbench navigation tab, Monaco editor, and database-to-code mapping badges:

1. Open your target environment configuration:
   • Development: ui/src/environments/environment.ts
   • Production: ui/src/environments/environment.prod.ts
2. Set enableGitIntegration: true:

   export const environment = {
     production: true, // or false in dev
     enableGitIntegration: true,
     // ...
   };
   

3. Build or restart the UI application:

   cd ui && npm run build
   

Technical Workflows

1. Repository Discovery, Cloning & Pulling

When the Workbench is active, the top toolbar provides full repository control:

• Existing Repositories: The API scans the active workspace (GET /api/git/repositories) and lists all discovered Git repositories.
• Clone Remote Repository: Click Clone New Repo to provide:
  • Git Remote URL: HTTPS (https://github.com/org/repo.git).
  • Folder Name: Target folder name in the workspace.
  • Branch: Optional initial branch (defaults to remote default branch).
  • Clones use --depth 1 (shallow clone) by default to prevent filesystem exhaustion.
• Pull Latest Changes: Click Pull (POST /api/git/pull) to fetch and fast-forward/rebase the latest commits from the remote branch using active session credentials.

2. Branch Viewing & Switching

• Active Branch Display: The toolbar detects the checked-out branch directly from .git/HEAD (e.g. main, master, feature/x) and displays the available local branches.
• Switch Branch: Select a branch from the dropdown to check it out immediately and reload the file explorer.
• Create Branch: Click + to create and switch to a new branch.

3. Dependency Indexing (.visulate/<db>/oracle-code-map.json & .visulate/<db>/codebase-dependencies.md)

The indexing engine analyzes the relationship between the active database connection and the repository source code:

1. In the Workbench, select a Database Connection (e.g., pdb21) and click Index DB Map in the toolbar.
2. The API calls POST /api/git/index-dependencies:
   • Queries the database catalog using DBA_OBJECTS (with fallback to ALL_OBJECTS in Oracle or information_schema in Postgres) for all valid user-defined tables, views, packages, procedures, functions, sequences, and types. System schemas (SYS, SYSTEM, etc.) and PUBLIC synonyms are excluded so that application schemas are discovered comprehensively.
   • Recursively scans the project files for references to these catalog objects across DDL statements, SQL query clauses (FROM, JOIN, INTO, UPDATE, EXEC, CALL, etc.), and application code.
   • Writes the cross-reference index to .visulate/<db>/oracle-code-map.json and human-readable Markdown to .visulate/<db>/codebase-dependencies.md in the repository (where <db> is the database connection name, e.g. pdb21).

4. Bi-Directional Database-to-Code Navigation

Once .visulate/<db>/oracle-code-map.json exists:

• From the Database View: Navigating to an object in the Visulate Catalog (e.g., /database/pdb21/RNTMGR2/TABLE/PR_PROPERTIES) displays an accordion panel: Related Repository Code Files with “Mapped codebase files in {repo} ({count})”.
• One-Click Navigation: Clicking Open in Workbench on any referenced file navigates directly to /workbench?db=:db&projectId=:repo&file=:file, auto-selecting the repository in the Workbench and opening the file in Monaco Editor.
• From the Workbench File Tree: Files referencing database objects display visual badges indicating the count and names of matched schema objects.

5. AI Agent & MCP Server Integration

Codebase dependencies are fully integrated into Visulate’s AI agent architecture:

• Context Injection: When an agent requests object context via getContext, the API server resolves codebase dependencies using dependencyIndexer.getObjectCodeDependencies(). The resulting files and repository name are added to codebaseDependencies and associatedRepo.
• Prompt Formatting (ai-context.hbs): The Handlebars context template formats referencing codebase files into a structured section for LLM consumption.
• MCP Tool getCodebaseDependencies: Exposed on the Model Context Protocol (MCP) server, allowing agents like app_developer and object_analysis_agent to query codebase dependencies on demand to assess application impact and maintain OKF architectural memory.

6. File Editing, Diffs, and Committing

Within the Monaco editor:

• Edit and Save: Edit files directly in the browser and save via Ctrl+S / Cmd+S or the toolbar Save button (PUT /api/git/file).
• Diff View: Compare the working copy against HEAD (GET /api/git/diff) using Monaco’s side-by-side or inline diff viewer.
• Commit & Push: Click Commit & Push (POST /api/git/commit-push) to stage modified files, commit using your session author identity (user.name and user.email), and push to the remote branch using your session token.

API Reference Summary

Copyright © Visulate LLC, 2019, 2025 Privacy Policy