// Expert guidance for GabeDA v2.1 architecture (34 modules) - implementing models, features, debugging 4-case logic, and maintaining the /src codebase.
| name | architect |
| description | Expert guidance for GabeDA v2.1 architecture (34 modules) - implementing models, features, debugging 4-case logic, and maintaining the /src codebase. |
| version | 2.1.0 |
This skill provides expert guidance for the GabeDA v2.1 refactored architecture. It focuses on implementing models, adding features, debugging execution logic, and maintaining architectural principles across the 34-module /src codebase.
Core Expertise:
/src architecture (34 modules in 6 packages)Invoke this skill when:
/src refactored codebase (v2.1)/test folderNOT for: Business strategy, marketing content, data analysis notebooks (delegate to business, marketing, insights skills)
Essential Documents:
Key References:
34 modules in 6 packages following Single Responsibility Principle:
src/
โโโ utils/ # Utilities (7 modules) - 88 tests, 92% coverage
โโโ core/ # Core infrastructure (5 modules)
โโโ preprocessing/ # Data preparation (5 modules)
โโโ features/ # Feature management (4 modules)
โโโ execution/ # Feature computation (5 modules) - Includes 4-case logic
โโโ export/ # Output generation (2 modules)
For complete module details: See references/module_reference.md
CSV โ DataLoader โ SchemaProcessor โ SyntheticEnricher โ
FeatureStore โ DependencyResolver โ ModelExecutor โ ExcelExporter
For detailed flow stages: See references/data_flow_pipeline.md
The GroupByProcessor (src/execution/groupby.py) implements single-loop execution with 4 cases:
Case 2 Example:
def price_above_avg(price_total: float, prod_price_avg: float) -> bool:
"""Filter that uses an attribute as input"""
return price_total > prod_price_avg
For deep dive: See references/4_case_logic.md
When creating daily, weekly, monthly, customer, or product aggregation models:
/test folderDetailed guide: assets/examples/implementing_new_model.md
Working examples:
When adding filters (row-level) or attributes (aggregated):
/test folder with sample dataDetailed guide: assets/examples/adding_new_feature.md
For feature type details: See references/feature_types.md
When joining external datasets (daily โ weekly, customer โ product):
ctx.list_datasets()dt_date stays dt_date)price_total_sum โ daily_attrs_price_total_sum)Critical naming table:
| Column Type | Original | After Merge | Prefixed? |
|---|---|---|---|
| Join key | dt_date | dt_date | โ NO |
| Regular column | price_total_sum | daily_attrs_price_total_sum | โ YES |
Detailed guide: assets/examples/configuring_external_data.md
For complete naming rules: See references/external_data_integration.md
When encountering errors during model execution:
ctx.get_dataset('name').columns.tolist()Common error: "Argument not found"
Causes:
Solution:
# 1. Check input dataset
print(ctx.get_dataset('transactions_filters').columns.tolist())
# 2. Check external dataset
print(ctx.get_dataset('daily_attrs').columns.tolist())
# 3. Remember: Join keys NO prefix, others WITH prefix
For complete troubleshooting: See references/troubleshooting.md
CRITICAL: Always clean dev environment BEFORE starting new features
When working on frontend features (GabeDA Dashboard - React + TypeScript + Vite):
Step 0: Clean Dev Environment (MANDATORY)
# Kill all node processes to avoid port conflicts and HMR corruption
cd C:/Projects/play/gabeda_frontend
taskkill //F //IM node.exe
# Clear Vite cache
rm -rf node_modules/.vite
# Start fresh dev server
npm run dev
Why This Matters:
Quick Fix Script: Use restart-dev.bat in frontend folder:
@echo off
taskkill //F //IM node.exe 2>nul
if exist node_modules\.vite rmdir /s /q node_modules\.vite
npm run dev
Development Workflow:
restart-dev.bat or kill node processes manuallygit checkout -b feature/feature-name)npm run build to check for TypeScript errorsCommon Issues:
.vite cachePort Detection:
# Check which port Vite started on (look for "Local: http://localhost:XXXX")
npm run dev
# If not 5173, there are stuck processes - kill and restart
Best Practices:
npm run build) before committing to catch TypeScript errorsโ
Single Responsibility - Each module does ONE thing
โ
Single Input - Each model gets exactly 1 dataframe
โ
DFS Resolution - Features auto-ordered by dependencies
โ
4-Case Logic - Filters can use attributes as inputs
โ
Immutable Context - User config never changes during execution
โ
Save Checkpoints - Save after every major transformation
โ
Type Annotations - All functions have type hints
โ
Logging - Every module uses get_logger(name)
โ
Testing - All tests MUST be in /test folder and be repeatable
For detailed principles: See references/core_principles.md
Current Statistics:
Test Rules:
/test foldertest_{module_name}.py or test_{feature_name}.pyRunning Tests:
pytest test/ # All tests
pytest test/unit/ # Unit tests only
pytest test/integration/ # Integration tests only
pytest test/ -v # With verbose output
For complete testing guidelines: See references/testing_guidelines.md
Base Config:
base_cfg = {
'input_file': 'path/to/data.csv',
'client': 'project_name',
'analysis_dt': 'YYYY-MM-DD',
'data_schema': {
'in_dt': {'source_column': 'Fecha venta', 'dtype': 'date'},
'in_product_id': {'source_column': 'SKU', 'dtype': 'str'},
'in_price_total': {'source_column': 'Total', 'dtype': 'float'}
}
}
Model Config (With External Data):
cfg_model = {
'model_name': 'weekly',
'group_by': ['dt_year', 'dt_weekofyear'],
'row_id': 'in_trans_id',
'output_cols': list(features.keys()),
'features': features,
'external_data': {
'daily_attrs': {
'source': 'daily_attrs',
'join_on': ['dt_date'],
'columns': None # None = ALL, or ['col1', 'col2']
}
}
}
For complete patterns: See references/configuration_patterns.md
When making changes, ALWAYS append to these 9 living documents:
| Document | When to Use |
|---|---|
| CHANGELOG.md | After modifying any .py file |
| ISSUES.md | After fixing bugs or errors |
| PROJECT_STATUS.md | Weekly updates |
| FEATURE_IMPLEMENTATIONS.md | After implementing features |
| TESTING_RESULTS.md | After running tests |
| TEST_MANIFEST.md | When adding/modifying tests โญ |
| ARCHITECTURE_DECISIONS.md | When making architectural choices |
| NOTEBOOK_IMPROVEMENTS.md | When improving notebooks |
| FUTURE_ENHANCEMENTS.md | When proposing enhancements |
Documentation Workflow:
Architect Workspace: .claude/skills/architect/
Bundled Resources:
references/ - 11 technical reference documents (module structure, 4-case logic, external data, testing, troubleshooting, core principles)assets/examples/ - 4 implementation guides (new model, new feature, external data, aggregation level)Technical Documents (Create Here):
/ai/architect/ - Architecture proposals, spike results, design documentsintegration_analysis.md, feature_implementation_guide.mdContext Folders (Reference as Needed):
/ai/backend/ - Django backend context/ai/frontend/ - React frontend context/ai/specs/ - Technical specifications (context, edge cases, feature store, model specs)Always explain:
/test folderFor every change:
/test folderdata/tests/ when neededThink like an architect: Prioritize maintainability, testability, and adherence to established patterns.
v2.1.0 (2025-10-30)
references/ (11 files) and assets/examples/ (4 files)v2.0.0 (2025-10-28)
Last Updated: 2025-10-30 Architecture Version: v2.1 (34 modules in 6 packages) Test Coverage: 197 tests, 85% coverage Core Innovation: 4-case logic engine (filters can use attributes as inputs)