Refactor: Replace Gold/Silver/Bronze Terminology with Meaningful Names

Problem

The current codebase uses mining/metals terminology (Gold, Silver, Bronze) to describe data layers. While this follows a common data engineering pattern, the names don't clearly communicate what each layer does:

• Bronze → Raw data ingestion
• Silver → Normalized/transformed data
• Gold → Analytics/aggregated data ready for consumption

This makes the code harder to understand for new contributors who aren't familiar with the medallion architecture pattern.

Proposed Changes

Layer Renaming

Current	Proposed	Rationale
Bronze	Raw	Clearly indicates unprocessed data from GitHub API
Silver	Normalized (keep as-is)	Already descriptive
Gold	Analytics or Ready	Describes purpose: aggregated data ready for frontend

Files & Folders to Refactor

Database Schema

• bronze.github_events → raw.github_events
• bronze.github_users → raw.github_users
• bronze.github_repos → raw.github_repos
• bronze.processing_queue → raw.processing_queue
• gold.user_profile → analytics.user_profile or ready.user_profile
• gold.user_activity → analytics.user_activity
• gold.repository → analytics.repository

Migration needed: 17XXXXXXXXXX-RenameSchemasToRawAndAnalytics.ts

Source Code

Variables & Types:

// Before
interface BronzeRow { ... }
interface BronzeEventsRow { ... }
interface BronzeUsersRow { ... }

// After
interface RawEventRow { ... }
interface RawEventsRow { ... }
interface RawUsersRow { ... }

Functions:

// src/raw/raw-saver.ts
insertBronze() → insertRawEvent()
upsertBronzeUser() → upsertRawUser()
upsertBronzeRepo() → upsertRawRepo()

Comments & Documentation:

// Before: "Dual write to Bronze DB + memory"
// After: "Dual write to Raw DB + memory"

// Before: "Silver layer normalization"
// Keep as: "Normalized layer transformation"

// Before: "Gold analytics aggregation"
// After: "Analytics layer aggregation"

Service Names (Optional - Breaking Change)

Consider renaming for consistency:

• SilverOrchestratorService → NormalizedOrchestratorService (already clear)
• AnalyticsService → Keep as-is (already clear)

Files Affected

Database Layer

• src/database/migrations/*.ts - All migrations with schema references
• src/analytics/user_profile/user_profile.entity.ts - Schema name in @Entity('gold.user_profile')
• src/analytics/user_activity/user_activity.entity.ts
• src/analytics/repository/repository.entity.ts

Raw Layer

• src/raw/raw.service.ts - All bronze.* table queries
• src/raw/raw-saver.ts - Function names and queries
• src/raw/raw-memory.store.ts - Interface names
• src/raw/raw.controller.ts - Comments and logs

Normalized Layer

• src/normalized/**/*.repo.ts - Queries referencing bronze.* tables
• src/normalized/orchestrator.ts - Comments

Analytics Layer

• src/analytics/**/*.repo.ts - Queries referencing gold.* tables
• src/analytics/analytics.service.ts - Comments and logs

Pipeline Layer

• src/pipeline/pipeline.service.ts - All layer references in comments and logs

Scripts

• src/scripts/*.ts - All debug scripts with schema references

Tests

• src/**/__tests__/*.spec.ts - Update terminology in test descriptions

Implementation Strategy

1. Phase 1: Database Migration

   • Create migration to rename schemas: bronze → raw, gold → analytics
   • Test on development database
   • Update all @Entity() decorators

2. Phase 2: Type Definitions

   • Rename interfaces: BronzeRow → RawEventRow, etc.
   • Update all imports

3. Phase 3: Function Names

   • Rename functions in raw-saver.ts
   • Update all callers

4. Phase 4: Comments & Logs

   • Find/replace "Bronze" → "Raw"
   • Find/replace "Gold" → "Analytics"
   • Keep "Silver" as "Normalized" (already descriptive)

5. Phase 5: Documentation

   • Update README.md architecture section
   • Update any existing docs

Breaking Changes

⚠️ Database schema rename requires migration - Existing deployments need migration script

✅ No API changes - Controllers remain the same

✅ No TypeScript breaking changes - Internal refactoring only

Benefits

• Improved Readability: insertRawEvent() is clearer than insertBronze()
• Self-Documenting: New developers understand layer purpose immediately
• Industry Standard: "Raw → Normalized → Analytics" is widely recognized
• Easier Onboarding: No need to explain medallion architecture upfront

Acceptance Criteria

• All database schema names updated (bronze → raw, gold → analytics)
• All type definitions renamed (BronzeRow → RawEventRow, etc.)
• All function names updated (insertBronze → insertRawEvent, etc.)
• All comments and log messages updated
• Database migration tested on development environment
• All tests passing
• README.md updated with new terminology

Priority

Medium - Improves code clarity but doesn't affect functionality

Labels

refactoring, good-first-issue, documentation

Related

• #[ISSUE_NUMBER] - Documentation Request (this refactor will make docs clearer)