Afunana builds a comprehensive data dictionary and cross-reference matrix from your source code. Together they form the data half of the knowledge graph: a complete map of what data exists, what it means, and how it flows through the system -- persistent, queryable, and refreshed as the code changes.
The primary worked example here is IBM i (DDS, COBOL, RPG, CL). The same dictionary and cross-reference are produced for Oracle collections from the Oracle data dictionary, and for plain SQL sources.
Overview
The data dictionary answers "what does this field mean?" The cross-reference answers "who uses it?" Field lineage answers "where does its value come from and where does it go?" Combined, they give analysts and developers a full picture of the data landscape without reading source code.
The dictionary is generated automatically during the build. Deterministic parsing extracts the structure; AI produces human-readable descriptions for every field and file. Manual edits are supported and preserved across rebuilds. Because it is rebuilt on every build (and surgically updated in incremental changes mode), it always reflects the current state of the code.
Field Catalog
The field catalog is the lowest level of the dictionary. Every unique field across all files in the collection gets an entry.
| Attribute | Description |
|---|---|
| Field Name | The field name as defined in DDS or source (e.g., CUSTNO, ORDAMT) |
| Data Type | Packed, zoned, character, date, timestamp, etc. |
| Length | Field length in bytes or digits |
| Decimal Positions | Number of decimal places for numeric fields |
| Is Key | Whether the field participates in a key |
| AI Description | Plain-language description of what the field represents |
| Files | Files that contain this field |
| Programs | Programs that reference this field |
| Shared fields | Related fields carried alongside it |
The AI description is the key value-add. Instead of guessing that CRDLMT means "credit limit," the dictionary states it with business context: "Customer credit limit in NIS. Checked during order validation to determine whether the order can proceed without manager approval."
Searching the Field Catalog
Fields are searchable by technical name, partial name, data type, or business description. The AI descriptions enable natural-language search across inconsistent naming conventions:
- Search "customer phone number" and find
WS-CUST-PH-NBR,CUST-PHONE,W-TELEPHONE-NO - Search "policy expiration date" and find
POL-EXP-DT,WS-POLICY-EXPIRY,EXPIRE-DATE - Search "account balance" and find every field that holds an account balance
This is invaluable when new team members learn the codebase, when analysts locate fields for regulatory requirements, or when multiple teams used different conventions over the years.
Table Documentation
Table-level entries document each file as a whole:
- File name and library
- Purpose -- description of what the file stores and its role in the application
- Record format name and description
- Complete field list -- all fields with types, lengths, and descriptions
- Key definition -- primary key fields, sort order, uniqueness
- Relationships -- logical files over this physical file, join relationships
- Access summary -- which programs read, write, update, or delete records
Table documentation is generated during file documentation in the build.
Application Groups
Application-level entries organize files and fields into logical business groupings:
- Customer Management -- CUSTMAST, CUSTADDR, CUSTCONT, and associated fields
- Order Processing -- ORDERHDR, ORDERDTL, ORDSTS, and associated fields
- Accounts Receivable -- ARINV, ARPMT, ARAGING, and associated fields
Groups are inferred by the LLM from file names, field overlap, and documented relationships, and can be adjusted manually.
Cross-Reference Matrix
The cross-reference maps programs to files with access-type detail -- a persistent structural fact, available from parsing alone before any AI runs.
Structure
Rows are programs; columns are files. Each cell indicates how the program accesses the file.
| Access Type | Symbol | Meaning |
|---|---|---|
| Read | R | Program reads records from the file |
| Write | W | Program writes new records to the file |
| Update | U | Program modifies existing records |
| Delete | D | Program deletes records |
A single cell may combine access types (e.g., "R/U").
Sorting and Ranking
Files and programs are ranked by impact count -- the number of programs that depend on them. A file used by 40 programs ranks above one used by 3, telling you immediately which data structures are central to the system and which are peripheral.
Filtering
Filter by program, file, access type (e.g. only programs that write, or only programs that delete), or library.
Use Cases
- Impact analysis -- "If I change the structure of CUSTMAST, which programs are affected?" Filter to the CUSTMAST column.
- Security review -- "Which programs can delete records from the payment file?" Filter to ARPMT, access type D.
- Dependency mapping -- "What files does the month-end batch touch?" Filter to the batch program rows.
Field Lineage -- Across Program Boundaries
Field lineage traces how a value flows from one field to another, and it does not stop at program boundaries. This is where the knowledge graph pays off: when a field is passed as a CALL parameter, the lineage follows it into the called program and keeps tracing, giving end-to-end visibility across the whole estate.
Starting from a selected field, the lineage view shows:
- Origin -- where the value is first created: user input, file read, screen input, system variable, literal.
- Transformations -- every program that reads the field, applies logic, and writes a result elsewhere. Each transformation records source field(s), target field(s), and the program where it occurs, tracing MOVE, COMPUTE, STRING, UNSTRING, and arithmetic operations.
- Destinations -- final resting places: file writes, screen outputs, report lines, CALL parameters, return codes.
Every referencing line is classified by role -- DEFINITION, MOVE, READ, WRITE, COMPUTE, CALL, CONDITION, or PERFORM -- and the tracer is alias-aware and COPY-REPLACING-aware, so renamed and copybook-substituted fields are followed correctly. Source and target files are separated by I/O direction.
The visualization renders as a directed graph: nodes are programs, edges are labeled with the field names read and written. Clicking a node opens the program details.
Impact Analysis
Impact analysis combines the stored change-impact reports, the cross-reference matrix, and field lineage to answer "what breaks if I change this?"
The per-file change-impact narratives on the File Details page (the "Impact" section) are build-time artifacts, not live queries -- generated during the collection-artifacts stage alongside the system overview and data dictionary, and refreshed whenever the collection is rebuilt (or, in changes mode, when the affected files are regenerated). See Build Process. The interactive impact views combine these stored reports with the live cross-reference and lineage.
Given a proposed change -- modifying a field length, removing a file, changing a program's output -- the system identifies:
- Direct impacts -- programs that directly reference the changed element
- Indirect impacts -- programs that consume output from directly impacted programs
- Data-flow impacts -- downstream fields that derive their values from the changed field
- Copybook impacts -- every program that includes an affected copybook
Recommended Compile Order
When a change spans multiple programs, they must be recompiled in the right order. Afunana derives a recommended compile order from the call graph.
Change Scenarios
| Scenario | What Afunana Reports |
|---|---|
| Field size change | All files and programs referencing the field; byte-offset shifts for subsequent fields |
| Field type change | Programs with arithmetic or comparisons that may become invalid |
| New field added to record | Programs that reference the record by byte position rather than field name |
| File removed or renamed | Every program that opens or references the file |
| Copybook modification | Every program that includes the copybook, with which fields are used |
Impact analysis is available from the Data Lineage page and from AI Chat -- ask "what would be impacted if I change field X?" and the answer arrives cited to specific programs and lines. See Chat Capabilities.
Building the Dictionary
Extraction (parse stage)
Deterministic parsing extracts field definitions, file structures, and cross-references from the source (DDS/COBOL/RPG/CL for IBM i; the Oracle data dictionary and PL/SQL for Oracle).
The same source always produces the same dictionary.
AI Enrichment (documentation stage)
Field names, data types, and surrounding context are sent to the LLM, which generates business descriptions for each field and file from naming patterns, usage context, and program logic.
Compilation (collection-artifacts stage)
The cross-reference matrix is compiled and the field-, table-, and application-group-level entries are assembled, alongside the system overview and change-impact reports.
Indexing
Vector embeddings (local model) and the BM25 keyword index are built in the following stage so the dictionary is searchable in chat.
Manual Editing
AI-generated descriptions can be edited on the Data Dictionary page. Edits are preserved across rebuilds -- the build detects existing manual overrides and does not overwrite them.
Export
The data dictionary and cross-reference matrix export as CSV from the Downloads page, for integration with external documentation systems and compliance workflows.