Administration Guide

This guide covers day-to-day administration of Afunana through the Admin panel.

Admin Panel Overview

The Admin panel is accessible at /admin by users with the admin role. It contains the following sections:

A collection's platform is derived from the connection it binds to — there is no separate platform field on the collection.

In-Context Field Help

Every admin and settings screen carries per-field help. Each field exposes a short who / what / where / when / why explanation inline, and each page has an Explain modal that describes the screen and its fields in plain language. This lets an administrator understand what a setting does — and when to change it — without leaving the page or consulting this guide.

Managing Collections

A collection represents a set of source from a single system or application. Collections are the primary organizational unit in Afunana. Each collection binds to a connection (Admin > Connections), and it inherits its platform — IBM i, Oracle, or z/OS — from that connection. The source-scope fields differ by platform (an IBM i library vs an Oracle schema), but everything downstream — analysis, docs, checks, chat — is identical.

Creating a Collection

1. Navigate to Admin > Collections.
2. Click Create Collection.
3. Fill in the required fields:

1. Click Save.

Configuring a Collection

Each collection has additional settings for source extraction. The example below is for an IBM i collection; an Oracle collection instead scopes by schema/owner (and object types).

Assigning Users

Only assigned users (and admins) can view and interact with a collection's content and chat.

1. Open the collection's edit page.
2. In the Assigned Users section, add or remove users.
3. Save changes.

Collection Actions

From a collection you can run these actions; each streams a live log and status on the Collections page:

Collection Status

Managing Connections

Admin > Connections manages the source-platform endpoints collections extract from. Each connection has a type — IBM i (AS/400), Oracle, or z/OS — plus identity fields (name, host, port, username, password, SSL) and platform-specific settings. Passwords are stored encrypted and shown masked.

The editor's left side holds the fixed identity fields; the right side shows the per-type settings (fetched from the connection schema). Admins can also add custom key/value fields per connection. For the full per-platform reference, authorities, and the IBM i component install, see Source Platform Integration.

Managing Users

Creating a User

1. Navigate to Admin > Users.
2. Click Add User.
3. Fill in the fields:

Roles

SSO Users

When SSO is configured, users are auto-provisioned on their first login. No manual account creation is needed. SSO users appear in the Users list with their SSO-provided attributes.

Disabling a User

Set is_active to false on the user's edit page. Disabled users cannot log in. Their data and history are preserved for audit purposes.

Force Logout

Revoke all active sessions for a user without deactivating the account. The user must log in again on their next visit.

Tags & Classification

Tags classify programs and files for filtering and organization.

Creating Tags

1. Navigate to Admin > Tags.
2. Click Add Tag.
3. Enter the tag key (internal identifier), display labels, color, and entity type (program or file).

Auto-Tagging

During the build pipeline, the AI automatically assigns tags to programs based on their business function. Tags can be manually overridden after the build completes.

Tag Filtering

Users see tag pills on the Programs and Files pages. Clicking a tag filters the list to matching items.

Build Management

Builds analyze source code and generate documentation, embeddings, and metadata for a collection.

Starting a Build

1. Navigate to Admin > Collections.
2. Select a collection.
3. Click Build.
4. Choose a build mode.

Build Modes

Choose full, continue, programs_only, files_only, system_only, or changes (incremental delta). Each mode and the five build stages are described in Build Process.

Monitoring a Build

Active builds stream their log output in real time on the Collections page. The log shows each step: source extraction, LLM analysis, embedding generation, and indexing.

Builds can be paused, resumed, or cancelled. Cancelling a build preserves any programs that were already processed.

Note: If a build process is killed or interrupted abruptly (e.g. the container is restarted mid-build), the collection can be left showing a stale error status even though nothing is wrong. Start a new build (or a continue build) to clear it.

Build History

Every build is recorded with:

• Start and end timestamps
• Build mode used
• Number of programs processed
• Success or failure status
• Error details (if failed)

View build history from the collection's detail page or from Logs > Build History.

Configuration

Navigate to Admin > Settings > Configuration to view and edit application configuration.

Settings are grouped by category: API Keys, AS/400, LLM, Builder, Chat, Organization, Security, Audit, Email, Timeouts. Secret values (API keys, passwords) are masked in the UI — edit them to set a new value; the existing value is never revealed.

For the full list of configuration keys, the two precedence chains (bootstrap keys vs. everything else), and the admin/dev/hidden visibility levels, see the Environment Configuration reference.

AI Config — One AI Hub

Navigate to Admin > Settings > AI Config. Every LLM call in Afunana routes through one governed gateway — the One AI Hub — so the organization controls cost, access, and data, and can switch providers or models with no rebuild.

Providers

Four providers are supported:

Roles and Fallback Chains

Work is routed across 11 specialized roles (program docs / builder, file docs, SQL docs, system overview, chat planner, chat answer, chat answer simple, chat classifier, code developer, spec doc, attachment OCR). Each role takes a comma-separated provider:model fallback chain — the router tries each in order until one succeeds:

Per-call token telemetry is captured, so cost is measurable per role. Changing a model takes effect live (no restart); changing a provider API key requires a restart (the UI notes this).

Presets

Presets are named per-role model bundles stored in the database — e.g. Anthropic+OpenAI, Anthropic-only, OpenAI-only, Azure-only, Local/Ollama. Applying a preset snapshots the current config first, so it is reversible.

Model Advisor

The model advisor calls each provider's live Models API with your own key (not an LLM call — it can't hallucinate model names), classifies the returned models into tiers, maps tiers to roles, and diffs against your current configuration to flag when a newer model is worth adopting. It is read-only; applying its recommendation is a separate, explicit step.

For the role catalog and the shipped per-role defaults, see AI & Analysis Pipeline.

Check Settings

Admin > Settings > Check Settings controls Afunana's deterministic (no-LLM) quality checks — the silent-failure layer that catches defects producing no error message. Each check has a severity you set per customer:

Each check ships a catalog default; the UI groups checks by language and family.

COBOL Checks

The parameter/interface mismatch checks (count + byte-size/structure, from a real data-division parser) are the strongest, headline COBOL checks.

PL/SQL Checks (14 rules)

Default error: plsql_swallow_exception, plsql_dml_no_where, plsql_dynamic_sql_injection, plsql_ddl_dynamic, plsql_null_comparison, plsql_hardcoded_credentials, plsql_commit_in_loop.

Default note: plsql_when_others_no_reraise, plsql_high_complexity, plsql_dead_private, plsql_select_star, plsql_insert_no_columns, plsql_goto, plsql_dbms_output.

Severities persist in the CHECK_SETTINGS config key as JSON — edit them here rather than by hand.

Logs & Monitoring

App Log

Logs > App Log shows the live application log stream. Filter by log level (DEBUG, INFO, WARNING, ERROR) and search by keyword.

Security Audit Log

Logs > Audit Log displays security-relevant events: logins, failed login attempts, configuration changes, user management actions, and data exports.

Each audit entry is part of a hash chain. The system verifies chain integrity and flags any gaps or tampering.

Filtering options: event type, actor, severity, date range. Export as CSV or JSON.

Chat Log

Logs > Chat Log shows chat session transcripts. Filter by user, collection, and date range. Each session shows the full conversation with timestamps and token counts.

Plan Log

Logs > Plan Log records change plans generated in Plan mode — the structured, validated modification plans (title, summary, steps) grounded in the live codebase. Each entry shows the plan, its status (pending_approval / approved / rejected), and, where execution is enabled, the outcome of applying it.

Build History

Logs > Build History lists all builds across all collections with status, duration, program count, and error count.

Deploy History

Logs > Deploy History tracks application version changes with version numbers and timestamps.

SQL Trace

Logs > SQL Trace captures database queries for debugging. This is a developer tool and is disabled by default.

Deploy

Admin > Deploy shows the running application version and whether a newer version is available (checked hourly against latest-version.json, non-blocking). For customers, updating means pulling a new image and restarting — see Deployment & Updates. Versions use the zero-padded XX.XX.XX format (e.g. 00.18.57). The developer-side deploy pipeline (GitHub Actions → Docker Hub) is separate and never touches customer servers.

Compliance

The Compliance section provides an overview of audit readiness and exposes the evidence surfaces auditors ask for.

Afunana's controls are mapped to OWASP Top 10 (2021), ISO/IEC 27001:2022, and SOC 2 — a documented control mapping, not a third-party certification (formal certification is in progress). The compliance status flags assert configuration (e.g. TLS, DB encryption) rather than actively probing your transport, so treat them as configuration attestations, not live proof.

Project Management

The Project tab provides lightweight project management for tracking documentation and migration work.

Epics

Group related work into high-level initiatives. Each epic contains a set of tasks and shows aggregate progress.

Tasks

Create, assign, and track individual work items. Each task has a title, description, assignee, priority, and status.

Kanban Board

Visualize tasks across workflow stages: To Do, In Progress, Done. Drag tasks between columns to update their status.

Project management is accessible to users with admin or qa roles.

Specification Documents

Formal specification documents (Business Specification, Systems Analysis, Program Specification) can be generated on demand from the Programs page (per-program) or the System Overview page (collection-wide), and exported as DOCX or PDF. See Program Documentation for the three levels and their contents.

Prompt Management

Admin > Prompts allows editing the system prompts that control AI behavior.

Changes take effect on the next build or chat query.

Report a Bug

Afunana includes an in-app Report a Bug page so users can send a problem report — a description plus the context of what they were doing — to the support mailbox without leaving the application. The feature is gated by configuration: the page appears only when BUG_REPORT_ENABLED is on, and submitted reports are emailed to the address set in BUG_REPORT_EMAIL. If no destination address is configured, reports are stored rather than emailed. Both keys are covered in Environment Configuration.

Operations & Setup Guide

Admin > Operations hosts system operations and the IBM i Components installer (pre-flight, install, and update of the TTDOC library — see Source Platform Integration).

The Setup Guide is an in-app operations checklist that walks a new administrator through first-run configuration in order: create a source connection, install the IBM i component (if applicable), set at least one LLM provider key and per-role models, set the organization name and public URL, configure SMTP and SSO if wanted, and run the first build. It mirrors the steps in Installation so an admin can complete setup without leaving the app.