Program Documentation

Afunana generates structured, AI-powered documentation for every program in your codebase. Each program receives a comprehensive document that captures its purpose, behavior, dependencies, and business context -- the knowledge that typically exists only in the heads of senior developers, or nowhere at all.

Documentation is produced for the source that actually runs the business: COBOL, RPG, CL, and DDS on IBM i, PL/SQL packages and procedures on Oracle, and plain SQL — all supported. z/OS COBOL analysis is on the near-term roadmap, built on the same approach. Throughout this page, IBM i is used as the primary worked example because that is what the screenshots show; the same document structure and "why layer" apply to Oracle PL/SQL and SQL, with the parser and quality checks made language-aware.

This is not a chat window explaining a snippet you paste into it. Afunana reads the whole estate, reconstructs a persistent cross-referenced map of it, and documents each program in the context of everything it calls, everything that calls it, and every file it touches.

Documentation Levels

Every program is documented at three levels, each targeting a different audience.

All three levels are generated from the same source-code analysis and cross-reference context. The LLM adjusts depth and terminology for each audience, but every level is grounded in the same parsed structural model.

Document Structure

Each program document is a structured record with the following sections.

The "Why" Layer

Legacy source records what the system does but almost never why. Afunana's highest-value output is the layer that reconstructs intent: business rules, hidden couplings, dead code, and migration traps. This is the knowledge that walked out the door when the original team retired.

Business Rules

The LLM examines conditional logic, validation checks, and branching paths to extract rules that are embedded in code but were never written down.

Examples of extracted rules:

• "Orders exceeding 50,000 NIS require manager approval (checked via field ORDAPR flag)"
• "Customer discount is capped at 15% unless override flag DSKOVR is set to 'Y'"
• "Batch processing skips records with status code '99' -- these are soft-deleted"

Each rule includes:

Every rule carries a source citation (see below) so reviewers can verify it against the actual code.

Dead Code, Implicit Dependencies, and Migration Traps

• Dead code -- unreachable paragraphs, unused 77-level fields, and commented-out logic are surfaced so they are not carried forward blindly into a modernization effort.
• Implicit dependencies -- couplings that never appear in a CALL: shared data areas, system values, hardcoded library or path assumptions, and environment expectations. These are the traps that make a "simple" change break something three programs away.
• Migration notes -- deprecated constructs, platform-specific features, and refactoring candidates flagged specifically for a modernization or re-platforming project.

Together these make the documentation useful not just for maintenance but for the decision to modernize -- you see the traps before you commit to the move.

Diagrams and Visual Maps

Afunana renders program and collection structure as interactive diagrams. Because the underlying cross-reference is a persistent graph, these are real maps of the system, not one-off sketches.

Diagrams are interactive: clicking a node scrolls the code viewer to the corresponding source lines, so a diagram is always a jumping-off point back into the real code.

Change-Impact Report

Every program and file carries a change-impact narrative that answers "what breaks if I change this?" It combines the persistent cross-reference and call graph with the documented behavior to describe direct impacts (programs that reference the element directly), indirect impacts (programs that consume their output), data-flow impacts (downstream fields), and copybook impacts (every program that includes an affected copybook). These narratives are generated as build-time artifacts and refreshed whenever the collection is rebuilt or the affected members change. See Data Dictionary & Cross-Reference for how they combine with live cross-reference and lineage queries.

Source Citations

Every claim in the documentation links back to the source code. No generated text exists without a path back to the code -- this is what lets an auditor trust the output.

Example citation:

Two citation mechanisms are used:

Line references (PROGRAM:LINE). Small clickable badges display source line numbers (e.g., 142-158). They appear next to process-flow steps, business rules, error-handling conditions, and file-access descriptions. Clicking a badge opens the code viewer at that location.

Section references. For COBOL programs, section and paragraph names (e.g., PROCESS-RECORD, 2000-VALIDATE) appear as clickable badges that navigate to the named section in the code viewer.

The citation system ensures that every documentation consumer -- auditor, analyst, or developer -- can verify any statement against the original source. The same PROGRAM:LINE citations back every factual answer in the AI chat (see Chat Capabilities).

Interactive Rendering

Program documentation renders as interactive HTML in the Afunana UI.

Collapsible sections. Each major section (Files Used, Dependencies, Business Rules, etc.) can be expanded or collapsed, so large programs with dozens of file references stay navigable.

Split code/diagram panel. The Program Details page shows documentation on the left and, on the right, source code, a flowchart, the file list, called-programs list, or a field-lineage diagram -- toggled from a toolbar. A third panel can be opened for side-by-side documentation and source. Panels are resizable. Clicking a citation on the left highlights the matching source lines on the right.

Tabbed navigation. Switch between the three documentation levels (Business, Systems, Program) using tabs. Each tab renders the same structure at a different depth.

Section sidebar. A vertical sidebar of icon cards jumps to any section without scrolling -- Executive Summary, At a Glance, Process Flow, Business Rules, Files, Dependencies, Error Handling, Dead Code, Migration Notes, and more.

Program chat. A chat button opens an inline AI assistant scoped to the current program, answering from that program's documentation and source.

Search within document. Full-text search across all sections of a single program's documentation.

For a full tour of these screens, see UI Walkthrough.

PL/SQL Documentation (Oracle)

For Oracle collections the same three-level documentation, business-rule extraction, diagrams, and citations are produced, with the analysis made PL/SQL-aware. Packages, procedures, functions, and triggers are documented from the Oracle data dictionary and source, and the quality layer applies PL/SQL-specific checks (swallowed exceptions, DML without WHERE, dynamic-SQL injection, and more) rather than the COBOL interface and MOVE checks. Oracle is functionally end-to-end -- connect, build, document, chat -- with a few polish items still trailing the IBM i experience. See Code Quality Analysis and Build Process.

Multi-Language Output

Afunana generates documentation in any language. The output language is configurable per collection.

In every language, program names, field names, and code references remain in their original left-to-right form within the surrounding text, and right-to-left languages are rendered correctly. Every language uses identical document structure and section organization.

Document Storage

Generated program documents are stored as JSON files on disk, one file per program. The filesystem is the source of truth for the document bodies; the database holds collection and build metadata (program inventory, build status, quality findings, tags). The JSON structure enables:

• Programmatic access via the REST API and the MCP server
• Export to DOCX and PDF via the Downloads page
• Indexing into the vector and keyword indexes for RAG-powered chat
• Diffing between build runs to track documentation changes over time

Tags

During the final build stage, the system derives a taxonomy from the documented collection and auto-assigns tags to each program (business domain, subsystem, program role, and similar dimensions). Auto-tagging is additive -- tags created or assigned manually by an administrator are preserved and never overwritten by a rebuild. Tags appear as colored pills on the Programs list and drive tag-based filtering. See Build Process for how auto-tagging fits into the pipeline.

Specification Documents

In addition to the interactive documentation, users can generate formal specification documents on demand. These are structured prose documents formatted for printing or sharing outside the platform.

Documents are cached in the database and regenerated automatically when the underlying program is rebuilt. Available as DOCX or PDF.

Accuracy and Review

AI-generated documentation is a strong first draft, not an infallible oracle. Afunana provides several mechanisms to support review:

• Source citations let reviewers verify every claim against actual code
• Confidence indicators flag sections where the LLM had limited context
• Quality reports identify programs where documentation may be incomplete
• Manual editing allows subject-matter experts to correct or augment generated content
• Intent-unclear flags mark business rules where the AI could not determine the business purpose

The goal is not to replace human understanding but to capture the majority of program behavior automatically -- dramatically reducing the time needed for full, trustworthy documentation.