Skip to content

DATABASE.md

Latest commit

 

History

History
533 lines (379 loc) · 6.63 KB

DATABASE.md

File metadata and controls

533 lines (379 loc) · 6.63 KB

DATABASE.md

Overview

CodeBase Insight is designed around a fundamental idea:

Software understanding should be represented as structured knowledge.

The database therefore stores software knowledge rather than source code itself.

The goal is to model:

  • Repositories
  • Architectures
  • Modules
  • Components
  • Relationships
  • Documentation
  • Learning Paths
  • Insights

Understanding emerges from the relationships between these entities.

Design Philosophy

Traditional repository platforms focus on storing files.

Example:

Repository
↓
Folders
↓
Files
↓
Source Code

CodeBase Insight focuses on storing understanding.

Example:

Repository
↓
Architecture
↓
Modules
↓
Components
↓
Relationships
↓
Insights

The database is designed around software knowledge rather than implementation artifacts.

Core Knowledge Model

The platform follows the following hierarchy:

Repository
↓
Architecture
↓
Module
↓
Component
↓
Relationship
↓
Insight

Each layer contributes to software understanding.

Repository Entity

A repository represents a software system.

Examples:

  • Learn With Linga
  • MathLogic
  • ResultGrid
  • BugSense AI

Purpose:

  • System identification
  • Project metadata
  • Repository ownership
  • Learning entry point

Attributes:

Repository
├── id
├── name
├── description
├── github_url
├── primary_language
├── architecture_style
├── created_at
└── updated_at

Architecture Entity

Represents the overall software architecture.

Examples:

  • Layered Architecture
  • Client-Server Architecture
  • Component-Based Architecture
  • Monolithic Architecture

Purpose:

  • High-level understanding
  • Architectural classification
  • Design reasoning

Attributes:

Architecture
├── id
├── repository_id
├── name
├── description
├── architectural_style
└── rationale

Relationship:

Repository
↓
Architecture

One repository may contain one or more architectural views.

Module Entity

Represents major functional areas of a system.

Examples:

Frontend
Authentication
Content Engine
Knowledge Model
Progress Tracking

Purpose:

  • Responsibility separation
  • System organization
  • Boundary definition

Attributes:

Module
├── id
├── repository_id
├── name
├── description
├── responsibility
└── parent_module_id

Relationship:

Repository
↓
Module

Component Entity

Represents individual software units.

Examples:

Navbar
DomainPage
AuthService
ContentLoader
InsightCard

Purpose:

  • Fine-grained exploration
  • Responsibility mapping
  • Dependency analysis

Attributes:

Component
├── id
├── module_id
├── name
├── type
├── responsibility
├── file_path
└── description

Relationship:

Module
↓
Component

Relationship Entity

Represents software connections.

Examples:

Uses
Depends On
Calls
Extends
Implements
Imports
Contains

Purpose:

Understanding emerges through relationships.

Attributes:

Relationship
├── id
├── source_component_id
├── target_component_id
├── relationship_type
└── description

Example:

DomainPage
↓ uses
ContentLoader

Documentation Entity

Represents documentation connected to software entities.

Examples:

  • README
  • Architecture Notes
  • Design Decisions
  • Developer Guides

Purpose:

Connect understanding directly to implementation.

Attributes:

Documentation
├── id
├── repository_id
├── title
├── content
├── category
└── created_at

Insight Entity

Represents extracted understanding.

Examples:

Why React Router was chosen

Why this abstraction exists

Why content loading is dynamic

Why caching is required

Purpose:

Capture software reasoning.

Attributes:

Insight
├── id
├── repository_id
├── title
├── explanation
├── category
└── created_at

Learning Path Entity

Represents guided exploration.

Example:

Repository Overview
↓
Architecture
↓
Modules
↓
Components
↓
Relationships
↓
Insights

Purpose:

Help learners navigate systems systematically.

Attributes:

LearningPath
├── id
├── repository_id
├── name
├── description
└── difficulty_level

Learning Step Entity

Represents individual learning activities.

Examples:

Explore Repository Structure

Understand Module Responsibilities

Trace Request Flow

Explain Architecture

Attributes:

LearningStep
├── id
├── learning_path_id
├── title
├── description
├── sequence_order
└── expected_outcome

User Entity

Represents learners using the platform.

Purpose:

  • Progress Tracking
  • Personalization
  • Learning Analytics

Attributes:

User
├── id
├── email
├── name
├── created_at
└── updated_at

Progress Entity

Tracks learning progression.

Attributes:

Progress
├── id
├── user_id
├── learning_step_id
├── completion_status
├── completed_at
└── notes

Knowledge Graph Perspective

The database can also be viewed as a graph.

Repository
├── Architecture
├── Module
├── Documentation
├── Learning Paths
│
Module
├── Components
│
Components
├── Relationships
│
Relationships
├── Insights

This structure enables future repository intelligence capabilities.

Why PostgreSQL

The platform is fundamentally relationship-driven.

Examples:

Repository → Module

Module → Component

Component → Relationship

Relationship → Insight

Learning Path → Learning Step

Relational databases naturally support:

  • Referential integrity
  • Structured queries
  • Knowledge exploration
  • Relationship modeling

PostgreSQL provides a strong foundation for these requirements.

Current Scope

Version 1 focuses on:

  • Repository modeling
  • Architecture modeling
  • Module organization
  • Component relationships
  • Documentation organization
  • Insight capture

The objective is to validate the knowledge model before expanding the platform further.

Summary

The CodeBase Insight database is not designed to store source code.

It is designed to store software understanding.

By treating repositories, architectures, modules, components, relationships, and insights as first-class entities, the platform transforms software systems into structured, navigable knowledge.