Source Platform Integration

Afunana reads the source that actually runs the business and reconstructs the knowledge inside it. That source lives on different platforms, and Afunana is multi-platform by design: a collection binds to a connection, and the connection's type decides which platform pipeline extracts the source.

This guide covers the source connections Afunana extracts from. IBM i (AS/400) is used here as the primary worked example and is the most detailed. Oracle is supported (read-only, no Oracle client). z/OS is a defined connection type whose analysis support is on the near-term roadmap. Plain SQL source is analyzed through the same pipeline once imported.

Platforms at a Glance

All three write into the same knowledge-graph contract (the TT* CSVs the build pipeline consumes), so documentation, quality checks, cross-reference, chat, and citations work the same way regardless of platform.

Connections

Source endpoints are defined on the Connections screen (Admin > Connections), not in the flat configuration table. A connection is a named endpoint with a type; a collection points at a connection to inherit its platform.

Connection Model

Every connection, regardless of type, carries the same identity fields.

Beyond identity, each type exposes platform-specific settings (a key/value catalog, so a new platform never requires a schema change). Admins can also add custom fields (label + secret flag) per connection.

Test Connection. The Connections screen's Test button currently performs a TCP reachability check to the host/port. A full protocol-level login test is available for IBM i from the configuration Test Connection action (JDBC query against QSYS) and for Oracle via the build's import step (real login against the data dictionary).

IBM i (AS/400)

The IBM i integration is the most detailed. It connects over JDBC, installs a small server-side component, runs a read-only batch extraction, and pulls the results over FTP.

Extraction Workflow

1. Afunana connects to the IBM i via JDBC (using jt400.jar).
2. A batch job (SBMJOB) is submitted on the IBM i that runs the TTDOC extraction program.
3. Afunana polls for job completion.
4. Results are downloaded via FTP.
5. Source files and metadata are stored locally and processed by the build pipeline.

No changes are made to production objects. The extraction is read-only (source-analysis compiles use *NOGEN — no objects are created).

IBM i Prerequisites

User Profile & Authorities

Create a dedicated IBM i user profile for Afunana. It needs:

• Read (*USE) access to all source physical files that will be analyzed.
• Authority to submit batch jobs (SBMJOB) and to submit to the configured job queue (default QSYSNOMAX).
• *SAVSYS or *ALLOBJ for the initial TTDOC install (can be reduced to *CHANGE on TTDOC afterward).
• CRTCBLPGM, CRTBNDRPG, CRTCLPGM authority (used with *NOGEN for source analysis only — no actual compilation).

Using *ALLOBJ simplifies setup but is not required. You can grant specific source-file authorities instead.

IBM i Connection Fields

On the Connections screen, create a connection of type IBM i (AS/400).

Global extraction tuning (job timeout, poll interval, submit-job log level) is set in the configuration settings — see Environment Configuration.

IBM i Component (TTDOC) Installation

Afunana requires the TTDOC library on the IBM i to perform extraction. It is distributed as a save file (SAVF) bundled inside the application image.

1. Navigate to Admin > Operations > IBM i Components.
2. Click Run pre-flight to verify connectivity, OS level, and user authority.
3. Click Install to upload the SAVF and restore the TTDOC library.

The installer uploads the component's save file (SAVF) to the IBM i over FTP in binary mode, restores it into the TTDOC library, and verifies the library exists.

Updating — the IBM i Components page shows the installed and available versions; Update re-uploads and restores (with ALWOBJDIF(*ALL) to replace existing objects).

Manual install — if your security policy does not allow *SAVSYS on the configured user: download the manual install kit from the IBM i Components page, FTP the SAVF and restore it with an authorized profile, then grant *CHANGE on TTDOC to the Afunana user for future updates.

IBM i Source Extraction

1. Job submission — Afunana submits a batch job (SBMJOB) that runs the TTDOC extraction program. Job parameters come from the SBMJOB_* connection settings and the AS400_SBMJOB_* / AS400_EXTRACT_* tuning keys.
2. Processing — TTDOC extracts source members, call relationships, file structures, and field definitions into CSV files on the IFS.
3. Polling — Afunana polls for a completion flag at AS400_EXTRACT_POLL_INTERVAL (default 60s), up to AS400_EXTRACT_TIMEOUT (default 1800s).
4. FTP download — extracted files are downloaded to backend/Data/<collection>/.
5. Build pipeline — the build reads the source and metadata and runs the analysis chain.

Supported IBM i Source Types

IBM i Extraction Output (TT* Contract)

IBM i Troubleshooting

Common IBM i extraction problems, their causes, and the IBM i-side commands that resolve them are catalogued below.

Oracle

Oracle applications are extracted read-only into the same knowledge-graph contract the IBM i pipeline consumes, so documentation, quality checks, cross-reference, and citation-backed chat are all PL/SQL-aware.

How Oracle Connects

Afunana uses python-oracledb in thin mode — a pure-Python driver. There is no Oracle client to install and no agent on the database server. The connection is read-only, targeting the Oracle data dictionary. The DSN is service-based (host:port/service); a SID is not used.

Oracle Connection Fields

On the Connections screen, create a connection of type Oracle.

The login needs read access to ALL_OBJECTS, ALL_SOURCE, ALL_TAB_COLUMNS, ALL_TAB_COMMENTS, ALL_COL_COMMENTS, ALL_CONSTRAINTS, ALL_CONS_COLUMNS, and ALL_DEPENDENCIES.

What Oracle Extraction Captures

• PL/SQL units — packages (spec + body combined into one program), procedures, functions, and triggers, from ALL_OBJECTS / ALL_SOURCE.
• Tables and views + columns — from ALL_TAB_COLUMNS, with descriptions from ALL_TAB_COMMENTS / ALL_COL_COMMENTS (including non-English comments).
• Primary keys — from ALL_CONSTRAINTS (type P) + ALL_CONS_COLUMNS.
• Dependencies — call/use relationships from ALL_DEPENDENCIES.

All of this is written into the identical TT* CSVs (TTPGMOUT, TTFILOUT, TTFFDOUT, TTKEYOUT, TTPGM2PGM, TTPGM2FIL) plus one source CSV per unit, so the build pipeline treats an Oracle collection exactly like an IBM i one.

Oracle Quality Checks

The silent-failure layer includes 14 PL/SQL rules (swallowed exceptions, DML without WHERE, dynamic-SQL injection, = NULL comparisons, hardcoded credentials, COMMIT in a loop, SELECT *, and more). See Check Settings.

Honest nuance. Oracle is functional end-to-end (create connection → collection → build). A few polish items remain relative to IBM i — for example, the Connections screen's Test button does a TCP reachability check rather than a full Oracle login (the real login test runs during the collection's import step). Do not assume full parity with the IBM i path.

z/OS — architected, analysis on the roadmap

z/OS is a defined platform and connection type: it appears in the platform registry and the Connections type list, and the knowledge-graph foundation is shared with the other platforms. Analysis support is not yet available — the platform ships disabled until its analysis code lands, and there is no z/OS extraction today. Frame it as: architected for z/OS, with mainframe COBOL analysis on the near-term roadmap, built on the same approach proven on IBM i.

Platform-Agnostic by Design

None of the deployment choices change how a source platform connects: Docker or Podman, bundled or external SQL Server, bundled Caddy or a customer-managed proxy — the connection and extraction behavior are identical. Adding a platform is a data change (a new platforms / platform_fields entry and a connector), not a schema change, because connection settings are stored as a key/value catalog rather than fixed columns.