Database Models & Schema

Overview

DeepDoc uses SQLAlchemy as its primary ORM for database modeling and schema management. All core models are defined in deepdoc/scan_v2.py, which acts as the central schema file. The system supports evidence-driven clustering, endpoint bundling, and integration discovery, with models representing both business entities and artifact tracking.

Migrations are managed via SQLAlchemy-compatible migration tools (e.g., Alembic), with migration files auto-detected and tracked. For a high-level system context, see DeepDoc Architecture & System Overview.

SQLAlchemy is detected as the primary ORM. All models are Python dataclasses, suitable for both relational and document-style storage.

Entity-Relationship Diagram

Below is a complete ER diagram showing all detected models, their key fields, and relationships:

Tables / Models

`SymbolCluster` (`deepdoc/scan_v2.py:47`)

Column / Field	Type	Constraints	Description
cluster_name	string	NOT NULL	Business domain cluster name (e.g., "checkout")
description	string		Cluster description
symbols	list[string]		Symbol names in this cluster
line_ranges	list[tuple]		Line ranges per symbol
related_imports	list[string]		Imports related to this cluster

Relationships:

Referenced by GiantFileAnalysis.clusters (one-to-many)

Indexes: None declared.

Used by: Parsing & Source Analysis, Pipeline & Generation Engine

`GiantFileAnalysis` (`deepdoc/scan_v2.py:57`)

Column / Field	Type	Constraints	Description
file_path	string	NOT NULL	Path to analyzed file
line_count	int		Total lines in file
total_symbols	int		Number of detected symbols
clusters	list		List of `SymbolCluster` objects

Relationships:

has_many SymbolCluster (via clusters)

Indexes: None declared.

Used by: Parsing & Source Analysis

`EvidenceUnit` (`deepdoc/scan_v2.py:272`)

Column / Field	Type	Constraints	Description
file_path	string	NOT NULL	Path to evidence file
role	string		Role (handler, service, model, etc.)
symbols	list[string]		Relevant symbols
relevance	float		Relevance score (0.0–1.0)

Relationships:

Referenced by EndpointBundle.evidence (one-to-many)

Indexes: None declared.

Used by: Pipeline & Generation Engine, Public API Endpoints

`EndpointBundle` (`deepdoc/scan_v2.py:281`)

Column / Field	Type	Constraints	Description
endpoint_family	string	NOT NULL	Resource family (e.g., "orders")
methods_paths	list[string]		Methods and paths (e.g., "POST /orders")
handler_file	string		Handler file path
handler_symbols	list[string]		Handler symbol names
evidence	list		List of `EvidenceUnit` objects
integration_edges	list[string]		Integration names touched

Relationships:

has_many EvidenceUnit (via evidence)
has_many IntegrationIdentity (via integration_edges)

Indexes: None declared.

Used by: Public API Endpoints, Pipeline & Generation Engine

`IntegrationCandidate` (`deepdoc/scan_v2.py:551`)

Column / Field	Type	Description
signal_type	string	Type (http_client, sdk_import, etc.)
name_hint	string	Integration name hint
file_path	string	File where signal was found
evidence	string	Evidence line/pattern
confidence	float	Confidence score

Relationships: None.

Indexes: None declared.

Used by: Integration Discovery, Integration Discovery

`IntegrationIdentity` (`deepdoc/scan_v2.py:561`)

Column / Field	Type	Constraints	Description
name	string	NOT NULL	Canonical integration name
display_name	string		Human-readable name
description	string		Integration description
files	list[string]		Files involved
evidence	list[string]		Evidence lines
is_substantial	bool		Standalone doc page flag
party	string		"third_party", etc.

Relationships: None.

Indexes: None declared.

Used by: Integration Discovery, Integration Discovery

`ModelFileInfo` (`deepdoc/scan_v2.py:854`)

Column / Field	Type	Constraints	Description
file_path	string	NOT NULL	Model/schema file path
orm_framework	string		ORM framework name
model_names	list[string]		Detected model/class names
is_migration	bool		Migration file flag

Relationships: None.

Indexes: None declared.

Used by: Setup & Getting Started

`DatabaseScan` (`deepdoc/scan_v2.py:863`)

Column / Field	Type	Description
model_files	list	List of `ModelFileInfo` objects
migration_files	list[string]	Migration file paths
schema_files	list[string]	Schema definition files
orm_framework	string	Primary ORM framework
total_models	int	Total detected models

Relationships:

has_many ModelFileInfo (via model_files)

Indexes: None declared.

Used by: Setup & Getting Started

`ArtifactScan` (`deepdoc/scan_v2.py:873`)

Column / Field	Type	Description
setup_artifacts	list[string]	Setup artifact files
deploy_artifacts	list[string]	Deployment artifact files
test_artifacts	list[string]	Test artifact files
ci_artifacts	list[string]	CI artifact files
ops_artifacts	list[string]	Ops artifact files
database_scan	DatabaseScan	Database scan results

Relationships:

has_one DatabaseScan (via database_scan)

Indexes: None declared.

Used by: Setup & Getting Started, Testing & Continuous Integration

Relationships Summary

The schema is highly modular, with most relationships expressed via lists of objects (one-to-many). There are no explicit foreign keys, but logical relationships are enforced via object references.

Source Model	Target Model	Relationship Type	Field
GiantFileAnalysis	SymbolCluster	one-to-many	clusters
EndpointBundle	EvidenceUnit	one-to-many	evidence
EndpointBundle	IntegrationIdentity	one-to-many	integration_edges
DatabaseScan	ModelFileInfo	one-to-many	model_files
ArtifactScan	DatabaseScan	one-to-one	database_scan

All relationships are managed in-memory via Python lists. There are no enforced DB-level foreign keys.

If you need a visual class relationship diagram:

Migrations

Migrations are detected and tracked via the DatabaseScan.migration_files field (deepdoc/scan_v2.py:863). Migration files are auto-discovered based on common patterns (e.g., Alembic, Django, Prisma, TypeORM, Sequelize). Manual and data migrations should be placed in recognized migration directories.

Run migrations Use your ORM's migration tool (e.g., Alembic for SQLAlchemy) to apply schema changes.

Verify migration files Ensure all migration files are detected by DatabaseScan.migration_files.

Check for manual migrations If you have manual SQL/data migrations, document them in the migration directory.

For setup details, see Setup & Getting Started.

Query Patterns & Performance

Query Patterns: Most queries are simple object traversals (list, filter, group). Heavy joins are avoided by design; relationships are managed via in-memory lists.
N+1 Risks: Minimal, since evidence and integration edges are batch-loaded.
Denormalisation: Artifact and evidence scans are denormalized for performance.
Caching: No explicit caching layer is present in the schema. If you need caching strategies, refer to Pipeline & Generation Engine.

Batch processing is recommended for large evidence sets — see Pipeline & Generation Engine.

Configuration

Database connection settings are managed via environment variables and config files, auto-detected by setup patterns (e.g., .env.example, pyproject.toml). For connection pooling and read replicas, configure your SQLAlchemy engine accordingly.

Variable / File	Required	Default	Description
DATABASE_URL	Yes	None	Connection string
ORM_FRAMEWORK	No	sqlalchemy	ORM framework name
MIGRATION_DIR	No	None	Migration directory path

For environment setup, see Setup & Getting Started.

Database Models & Schema

Overview

Entity-Relationship Diagram

Tables / Models

`SymbolCluster` (`deepdoc/scan_v2.py:47`)

`GiantFileAnalysis` (`deepdoc/scan_v2.py:57`)

`EvidenceUnit` (`deepdoc/scan_v2.py:272`)

`EndpointBundle` (`deepdoc/scan_v2.py:281`)

`IntegrationCandidate` (`deepdoc/scan_v2.py:551`)

`IntegrationIdentity` (`deepdoc/scan_v2.py:561`)

`ModelFileInfo` (`deepdoc/scan_v2.py:854`)

`DatabaseScan` (`deepdoc/scan_v2.py:863`)

`ArtifactScan` (`deepdoc/scan_v2.py:873`)

Relationships Summary

Migrations

Query Patterns & Performance

Configuration

See Also

DeepDoc Architecture & System Overview

Parsing & Source Analysis

Pipeline & Generation Engine

Setup & Getting Started

Testing & Continuous Integration

Integration Discovery

Vinculum Warehouse Management Integration

On this page