1. Getting Started

What is Data Governance?

Data Governance is the practice of managing data as a strategic enterprise asset. It involves establishing policies, procedures, and standards to ensure data quality, security, compliance, and usability across the organization.

What This Platform Does

The Data Governance Platform provides a centralized system to:

Define & manage business terms in a standardized glossary
Map business terms to technical metadata (database tables & columns)
Track data lineage from source to target systems
Automate approval workflows with role-based governance
Leverage AI for term suggestions, definitions, and classifications
Monitor governance health through analytics and audit trails

Accessing the Platform

Training Mode (No Login)

Open the app URL directly. You enter Training Mode automatically. Explore all features freely — changes are saved in your browser session only.

Session Only

Authenticated Mode (Login)

Click Admin Login in the top bar. Enter your credentials. All changes persist to the database with full audit trail.

Persistent

Tip

Training Mode is ideal for learning the platform, running demos, and exploring features without affecting production data.

System Requirements

Modern web browser (Chrome, Firefox, Edge, Safari)
JavaScript enabled
Internet connection (for AI features)

2. Platform Overview & Navigation

Main Navigation Sidebar

The left sidebar is your primary navigation tool. It is organized into functional sections:

Section	Pages	Purpose
Learn	Concepts, Platform Guide, A-Z Glossary, Regulations	Educational resources and reference materials
Glossary	Browse Terms, Create Term, Taxonomy	Manage business terms and definitions
Organization	Domains, Metadata, CDE Registry	Structure and link business & technical data
Data Flow	Lineage List, Lineage Graph	Track data movement between systems
Operations	Approval Inbox, Upload	Manage approvals and bulk data imports
Insights	Analytics Dashboard, Audit Log	Monitor governance health and track changes
AI	AI Assistant, AI Settings	AI chat and provider configuration
Admin	User Management, Settings	System administration (admin only)

Top Bar

Vertical Selector — switch between industry datasets (top-left)
Mode Indicator — shows "Training Mode" badge or logged-in user name
Admin Login — access authenticated mode

Dashboard

The home page provides an executive overview with:

Stat Cards: Total Terms, Approved Terms, Pending Approvals, Critical Data Elements
Coverage Metrics: Metadata linkage %, lineage coverage %, active workflows
Charts: Terms by Domain (bar chart), Status Distribution (doughnut chart)
Recent Activity Feed: Latest 10 actions across the platform

3. Industry Verticals

The platform ships with four industry verticals, each pre-loaded with industry-specific data including domains, business terms, technical systems, lineage mappings, and sample users.

Vertical	Domains Example	Systems Example	Use Case
Banking	Retail Banking, Treasury, Risk, Compliance	Core Banking, EDW, Regulatory Reporting	Global bank governance
Insurance	Underwriting, Claims, Policy Admin, Actuarial	Policy System, Claims DB, Reinsurance	Multi-line insurer
Manufacturing	Supply Chain, Production, Quality, Logistics	ERP, MES, SCADA, Quality Lab	Industrial operations
Ecommerce	Catalog, Orders, Customers, Marketing	Product DB, Order System, CRM	Online retail platform

Switching Verticals

Click the vertical name at the top of the sidebar

Select the desired industry vertical from the dropdown

Confirm the switch — the database will be completely reseeded

The page reloads with the new industry-specific data

Important

Switching verticals resets the entire database with the selected industry's data. Any custom terms, domains, or lineage mappings will be lost. AI provider configurations are preserved across switches.

4. Training Mode vs. Authenticated Mode

Feature	Training Mode	Authenticated Mode
Login Required	No (default experience)	Yes
Data Persistence	Browser session only	Database (permanent)
Create / Edit Terms	Yes (session only)	Yes (database)
AI Features	Fully functional	Fully functional
Approval Workflow	Simulated	Full multi-step workflow
Upload Files	Validation only	Full import to database
Role-Based Access	All features visible	Enforced by role
Audit Trail	No logging	Complete audit log
Analytics	View-only	Full metrics & tracking
Indicator	Training Mode badge	User name displayed

How Training Mode Works

All write operations (create, edit, delete) are intercepted by the browser
Data is stored in sessionStorage using the TrainingStore system
AI calls still go to the server (API key is needed) but responses are cached locally
Changes are lost when you close the browser tab
A yellow Training Mode banner appears on pages where you can make changes

Tip

Training Mode is perfect for: learning the platform, running client demos, testing governance workflows, and exploring AI features — all without affecting real data.

5. User Roles & Permissions

Role	Access Level	Typical User
ADMIN	Full platform access — user management, settings, all CRUD operations	IT governance lead, system administrator
DATA_STEWARD	Create/edit terms, submit for approval, manage metadata, upload files, edit lineage	Data governance analyst, domain coordinator
DATA_OWNER	View terms, approve/reject terms for their domain, manage domain governance	Business unit head, department leader
DATA_CUSTODIAN	View terms, final approval authority, link & verify metadata	DBA, data engineer, DDPO
VIEWER	Read-only access to all glossary, lineage, and analytics pages	Stakeholders, data consumers, auditors

Dual-Approval Workflow

Steward Creates Term → Data Owner Reviews → Data Custodian Approves → APPROVED

At any step, a reviewer can reject the term with comments, sending it back to DRAFT status.

6. Business Glossary

Browse Terms

Navigate to Glossary > Browse Terms to see all business terms in a searchable, filterable table.

Filters Available

Search: Free-text search across term names and definitions
Domain: Filter by business domain
Status: DRAFT, PENDING_REVIEW, PENDING_APPROVAL, APPROVED, REJECTED, DEPRECATED
Classification: PUBLIC, INTERNAL, CONFIDENTIAL, HIGHLY CONFIDENTIAL, PII, PCI
CDEs Only: Show only Critical Data Elements

Table Columns

CDE indicator (star icon)
Term Name with definition preview
Domain
Classification (color-coded badge)
Status (color-coded badge)
Data Owner (may be inherited from domain)
Last Updated date

Create a New Term

Navigate to Glossary > Create Term to open the creation form.

Form Fields

Field	Required	Description
Term Name	Yes	The business name for this data concept
Definition	Yes	Clear, unambiguous description of the term
Business Context	No	How this term is used in business operations
Example Values	No	Sample data values (comma-separated)
Domain	No	Business domain this term belongs to
Classification	No	Sensitivity level (PUBLIC to PCI)
CDE	No	Mark as Critical Data Element
Data Owner	No	Person responsible for business decisions
Data Custodian	No	Person responsible for technical management
Synonyms	No	Alternative names (SYNONYM, ALIAS, ACRONYM)

AI Assist

Click the "AI Suggest" button after entering a term name. The AI will generate a suggested definition, business context, classification, example values, synonyms, and CDE recommendation. Click "Use All Suggestions" to apply them all at once.

Term Detail Page

Click any term name to view its full detail page with five tabs:

Overview: Definition, context, examples, synonyms, relationships, and properties
Technical Metadata: Linked database columns, derivation formulas, metadata linking panel
Lineage: Data flow visualization and mapping details
Workflow History: All approval actions with reviewer, decision, comments, and timestamps
Versions: Version history with links to previous versions

Term Taxonomy

Navigate to Glossary > Taxonomy to see a hierarchical tree view of terms and their relationships (parent/child/IS_A/IS_PART_OF).

7. Business Domains & Subject Areas

What Are Domains?

Domains are logical groupings of related business terms. For example, a Banking vertical might have domains like "Retail Banking," "Treasury," "Risk Management," and "Compliance."

Browse Domains

Navigate to Organization > Domains to see all domains displayed as cards showing:

Domain name and description
Number of terms in the domain
Number of subject areas
Domain owner

Domain Detail

Click on a domain card to see:

Subject Areas: Sub-categories within the domain
Terms List: All business terms belonging to this domain
AI Suggestions: Use AI to suggest subject areas and terms for the domain

Subject Areas

Subject areas help organize terms within a domain. For example, the "Retail Banking" domain might have subject areas like "Deposits," "Loans," and "Cards."

Ownership Inheritance

If a domain has a Data Owner assigned, all terms in that domain inherit the owner unless the term has its own explicit owner. An inheritance indicator icon appears next to inherited owners.

8. Technical Metadata

Metadata Explorer

Navigate to Organization > Metadata to explore technical metadata (database systems, tables, and columns).

Filters

System: Select a source system (e.g., Core Banking, EDW, Reports)
Table Name: Search for specific tables
Search: Free-text across table names, column names, and descriptions

Metadata Fields

Field	Description
System Name	The source system (e.g., EDW, CORE_BANKING)
Database / Schema	Database and schema location
Table Name	Physical table name
Column Name	Physical column name
Data Type	SQL data type (VARCHAR, INT, DATE, etc.)
Primary Key	Whether this column is part of the primary key
Nullable	Whether the column allows NULL values
Linked Term	Business term mapped to this column (if any)

Linking Terms to Metadata

From a Term Detail page > Technical Metadata tab, you can link the term to specific database columns:

Click "Link Metadata" button

Use the cascading picker: System → Table → Column, or use the search box

Choose link type: DEFINES, POPULATED_BY, DERIVED_FROM, or REFERENCED_IN

Click "Link" to create the mapping

Click the verify icon to mark the link as verified

Link Types Explained

Type	Meaning	Example
`DEFINES`	Authoritative source column	"Customer ID" DEFINES CUSTOMER.CUST_ID
`POPULATED_BY`	Downstream copy of data	"Customer ID" POPULATED_BY DIM_CUSTOMER.CUST_KEY
`DERIVED_FROM`	Input to a calculation	"Net Interest Margin" DERIVED_FROM INCOME.INTEREST_REVENUE
`REFERENCED_IN`	Indirect reference	"Account Type" REFERENCED_IN REPORTS.ACCT_RPT.TYPE_CD

9. Data Lineage

What is Data Lineage?

Data lineage tracks how data moves and transforms between systems — from source databases through ETL/ELT pipelines to final reports and analytics.

Lineage Mappings List

Navigate to Data Flow > Lineage to see all source-to-target mappings in a table showing:

Source System, Table, and Column
Target System, Table, and Column
Transformation Type (DIRECT, AGGREGATION, CALCULATION, LOOKUP, FILTER, etc.)
Linked Business Term (if mapped)

Interactive Lineage Graph

Navigate to Data Flow > Visualization for an interactive D3.js graph showing:

Nodes: Tables and systems (color-coded by system type)
Edges: Data flow connections with transformation type labels
Controls: Zoom, pan, drag nodes, filter by term or table, adjust depth (1-3 hops)

Color Legend

Color	System Type
Blue	Source Systems
Green	Enterprise Data Warehouse (EDW)
Amber	ODS / Staging
Purple	Reports & Analytics

Uploading Lineage Data

Lineage mappings can be uploaded in bulk using the ELT Mapping template from the Upload page. See Chapter 12: Bulk Upload for details.

10. Critical Data Elements (CDEs)

What is a CDE?

A Critical Data Element is a high-impact data field that requires special governance due to its importance to business operations, regulatory compliance, or risk management. Examples include Customer ID, Account Balance, Transaction Amount, and SSN.

CDE Registry

Navigate to Organization > CDE Registry for a dedicated view of all critical data elements with their technical mappings.

Registry Dashboard

Total CDEs: Count of terms marked as CDE
Total Mappings: Number of term-to-column links for CDEs
Verification Rate: Percentage of links that have been verified
Unmapped CDEs: CDEs without any technical metadata links (red indicator)

Per-CDE Detail

Each CDE card expands to show:

All database column mappings with system, table, column, data type
Link type and derivation formula (if applicable)
Verification status (verified by whom and when)
Domain and classification badges

Marking a Term as CDE

Check the "Critical Data Element" checkbox when creating or editing a term. AI suggestions may also recommend CDE status based on the term's definition and classification.

11. Approval Workflows

Workflow Process

The platform uses a dual-approval workflow to ensure governance quality:

DRAFT → PENDING_REVIEW → PENDING_APPROVAL → APPROVED

Status	Who Acts	Action
DRAFT	Data Steward	Creates term, clicks "Submit for Approval"
PENDING_REVIEW	Data Owner	Reviews business accuracy, approves or rejects
PENDING_APPROVAL	Data Custodian	Reviews technical completeness, gives final approval
APPROVED	—	Term is officially governed
REJECTED	—	Returned to DRAFT with reviewer comments

Approval Inbox

Navigate to Operations > Approval Inbox to see all pending workflows. Filter by:

All: All pending workflows
Owner Review: Waiting for Data Owner
Custodian Review: Waiting for Data Custodian

Taking Action

Approve: Click the green "Approve" button to move to next step
Reject: Click "Reject", enter comments explaining why, then confirm

12. Bulk Upload & Import

Navigate to Operations > Upload to import data from Excel (.xlsx) or CSV files.

Supported File Types

File Type	What It Imports	Key Columns
Glossary Import	Business terms into the glossary	term_name, definition, domain, classification, data_owner, is_cde
Data Dictionary	Technical metadata (systems, tables, columns)	system_name, database_name, schema_name, table_name, column_name, data_type
ELT Mapping	Lineage mappings (source to target)	source_system, source_table, source_column, target_system, target_table, target_column, transformation_type

Upload Steps

Download Template: Click the template download button for your file type

Fill Data: Populate the Excel template with your data (one record per row)

Select File Type: Choose the matching file type from the dropdown

Upload: Drag and drop the file or click to browse

Review Results: Check success count, duplicates skipped, and any errors

Tip

Duplicate records (matched by term name for glossary, or system+table+column for metadata) are automatically skipped. The results summary shows how many were skipped.

Upload History

View all past uploads at Operations > Upload > History with filename, status, row counts, and error details.

13. AI-Powered Features

Overview

The platform integrates with AI providers (Claude, OpenAI, Azure OpenAI) to assist with governance tasks. AI features work in both Training Mode and Authenticated Mode.

AI Capabilities

Feature	Where	What It Does
Suggest Definition	Create/Edit Term page	Generates definition, context, examples, synonyms, classification, and CDE recommendation
Suggest Subject Areas	Domain Detail page	Recommends sub-categories for organizing a domain
Suggest Domain Terms	Domain Detail page	Recommends business terms relevant to a domain and subject area
AI Chat Assistant	AI > Assistant page	Multi-turn conversation about data governance topics

Using AI Suggest on Terms

Go to Create Term and enter a term name (e.g., "Customer Lifetime Value")

Click the "AI Suggest" button in the suggestion panel on the right

Wait for the AI to generate suggestions (takes a few seconds)

Review each suggestion — click "Use" next to individual items or "Use All Suggestions" to accept everything

AI Chat Assistant

Navigate to AI > Assistant for a full chat interface. You can ask about:

Data governance best practices
How to define and classify business terms
Data lineage and metadata concepts
Compliance and regulatory questions (GDPR, HIPAA, etc.)

AI Provider Configuration

Admin users can configure AI providers at AI > Settings:

Add API keys for Claude (Anthropic), OpenAI, or Azure OpenAI
Set the default provider
Configure model, temperature, and max tokens per provider
Test connection to verify API key is valid

Note

AI features require at least one AI provider to be configured with a valid API key. The platform works without AI — you simply won't see the suggestion buttons.

14. Analytics & Audit

Governance Analytics Dashboard

Navigate to Insights > Analytics for governance health metrics:

Coverage Metrics

Terms with Definitions: % of terms that have a definition filled in
Terms with Classification: % of terms with a sensitivity classification
Terms with Owner: % of terms with a data owner assigned
Metadata Linkage: % of terms linked to at least one technical column
Lineage Coverage: % of terms that appear in lineage mappings

Additional Insights

Most Viewed Terms: Top 10 terms by page view count
Search Failures: Queries that returned zero results (identify gaps in your glossary)

Audit Log

Navigate to Insights > Audit Log for a complete record of all changes:

Entity type (business_term, domain, metadata, workflow, etc.)
Action (CREATE, UPDATE, DELETE, APPROVE, REJECT)
Changed values (before/after JSON)
Changed by (user name)
Timestamp

Compliance Tip

The audit log provides the evidence trail needed for regulatory compliance audits (GDPR, SOX, HIPAA). Every data governance action is tracked with who, what, and when.

15. Administration

User Management

Navigate to Admin > Users (admin only) to manage platform users:

Create User: Set username, display name, email, department, and roles
Edit User: Update user details and change role assignments
Role Assignment: Assign multiple roles to a single user (e.g., DATA_STEWARD + DATA_OWNER)

AI Settings

Navigate to AI > Settings (admin only) to configure AI providers:

Add/update API keys for Claude, OpenAI, or Azure OpenAI
Set default provider and model
Adjust temperature (creativity) and max tokens
Test connections to validate API keys

Vertical Switching

The vertical selector at the top of the sidebar allows admins to switch the entire platform between industry datasets (Banking, Insurance, Manufacturing, Ecommerce).

Data Export

Admins can export data as Excel files:

Glossary Export: All business terms with definitions, classifications, owners
Lineage Export: All source-to-target mappings
Data Dictionary Export: All technical metadata

16. Learning Center & Regulations

The Learn section in the sidebar provides educational content built into the platform:

Page	Content
Concepts & Principles	Core data governance concepts: data quality, stewardship, metadata management, lineage, classification
Platform Guide	How to navigate and use the platform effectively
A-Z Glossary	Interactive reference tool with governance terminology
GDPR	EU General Data Protection Regulation compliance guide
HIPAA	US Health Insurance Portability and Accountability Act guide
UAE Data Protection	UAE Federal Data Protection Law compliance guide
India DPDP Act	India Digital Personal Data Protection Act guide

17. Step-by-Step Workflows

Workflow A: End-to-End Term Governance

Create Term: Go to Glossary > Create Term. Enter name, click "AI Suggest" for definition. Fill in domain, classification, owner. Click "Create Term." Status: DRAFT

Submit for Approval: On the term detail page, click "Submit for Approval." Status changes to: PENDING_REVIEW

Data Owner Review: Owner goes to Approval Inbox, finds the term, clicks "Approve." Status: PENDING_APPROVAL

Data Custodian Approval: Custodian goes to Approval Inbox, reviews technical completeness, clicks "Approve." Status: APPROVED

Link Metadata: On term detail > Technical Metadata tab, click "Link Metadata." Pick System → Table → Column. Set link type to DEFINES. Click "Link."

Verify Link: Click the verify icon next to the link. Now visible in CDE Registry (if CDE).

Workflow B: Bulk Data Import

Download Template: Go to Upload page. Click template download for your file type (Glossary, Data Dictionary, or ELT Mapping).

Prepare Data: Fill the Excel template with your data. One record per row. Save the file.

Upload: Select file type, drag and drop file, click "Upload & Process."

Review: Check results — successes, duplicates skipped, errors. Fix any errors and re-upload if needed.

Workflow C: Building Data Lineage

Upload ELT Mappings: Use the Upload page with an ELT Mapping template filled with your source-to-target transformations.

Browse Lineage: Go to Data Flow > Lineage to see all mappings in a table.

Visualize: Go to Data Flow > Visualization for the interactive graph. Filter by term or table. Adjust depth.

View from Term: On any term detail page, click the Lineage tab to see that term's specific data flow.

Workflow D: AI-Assisted Domain Setup

Create Domain: Go to Domains, click "New Domain." Enter name (e.g., "Risk Management") and description.

AI Suggest Subject Areas: On the domain detail page, click "AI Suggest Subject Areas." Review and accept suggestions (e.g., Credit Risk, Market Risk, Operational Risk).

AI Suggest Terms: Click "AI Suggest Terms" for each subject area. Review and accept suggested business terms.

Refine: Edit each term, use "AI Suggest" for full definitions, then submit for approval.

18. Cloud Deployment

Environment Variables

The platform uses environment variables for all configuration. Set these in your cloud platform's dashboard:

Variable	Required	Description
`SECRET_KEY`	Yes	Flask session encryption key. Generate with: `python -c "import secrets; print(secrets.token_hex(32))"`
`FLASK_ENV`	Yes	Set to `production` for cloud deployment
`DATABASE_URL`	Yes (cloud)	Database connection string. PostgreSQL recommended: `postgresql://user:pass@host:5432/dbname`
`ANTHROPIC_API_KEY`	For AI	Claude (Anthropic) API key
`OPENAI_API_KEY`	For AI	OpenAI API key
`DEFAULT_AI_PROVIDER`	No	`claude`, `openai`, or `azure_openai`
`PORT`	No	Auto-set by most cloud platforms

Deployment Options

Docker

Build and run with the included Dockerfile:

docker build -t governance .

docker run -p 5000:5000 --env-file .env governance

Heroku / Render / Railway

Push your code and set environment variables in the dashboard. The included Procfile handles the rest.

Security

Never commit your .env file to version control. Use the platform's secret management features to store API keys securely. The included .gitignore protects sensitive files.

19. Glossary of Key Terms

Term	Definition
Business Term	A word or phrase representing a business concept (e.g., "Customer ID," "Net Revenue")
Domain	A logical grouping of related business terms (e.g., "Customer Management," "Risk")
Subject Area	A sub-category within a domain (e.g., "Deposits" within "Retail Banking")
Classification	Sensitivity level of data: PUBLIC, INTERNAL, CONFIDENTIAL, HIGHLY CONFIDENTIAL, PII, PCI
CDE	Critical Data Element — high-impact data requiring special governance
Technical Metadata	Physical database structures: systems, tables, columns, data types
Lineage	The path data takes from source through transformations to target
Data Owner	Person accountable for business decisions about data quality and usage
Data Custodian	Person responsible for technical management, security, and access control
Data Steward	Person who creates, maintains, and manages governance artifacts day-to-day
Workflow	Multi-step approval process (Steward → Owner → Custodian)
Vertical	Industry context with pre-loaded data (Banking, Insurance, Manufacturing, Ecommerce)
Training Mode	Non-authenticated mode for exploration with browser-only data persistence
Derivation Formula	The calculation rule for a derived data element (e.g., Revenue - Cost = Profit)
Synonym	An alternative name for a business term (SYNONYM, ALIAS, ACRONYM, ABBREVIATION)

20. Quick Reference Card

Common Tasks

I Want To...	Go To	Action
Find a term	Glossary > Browse	Type in the search box
Create a new term	Glossary > Create	Fill form, click "AI Suggest" for help
Edit an existing term	Term Detail page	Click "Edit" button
Approve a term	Operations > Inbox	Click "Approve" or "Reject"
Link term to column	Term Detail > Metadata tab	Click "Link Metadata", pick column
View data lineage	Data Flow > Visualization	Interactive graph with zoom/filter
Upload bulk data	Operations > Upload	Download template, fill, upload
Get AI suggestions	Create Term page	Click "AI Suggest" button
Chat with AI	AI > Assistant	Type question, select provider
Check governance health	Insights > Analytics	View coverage metrics and charts
View change history	Insights > Audit Log	Filter by entity type or action
Manage users	Admin > Users	Create/edit users and assign roles
Configure AI	AI > Settings	Add API key, test connection
Switch industry	Sidebar top	Click vertical selector, choose industry
Export to Excel	Glossary / Lineage pages	Click "Export" button
View CDE mappings	Organization > CDE Registry	Expand CDE cards to see links

Need Help?

Use the AI Assistant (AI > Assistant) to ask any data governance question, or explore the Learning Center (Learn section) for concepts and regulatory guides.