Skip to content

Commit 9b23dfa

Browse files
Genovese-FelipeGenovese-Felipe
authored
Merge pull request #34 from Genovese-Felipe/copilot/fix-33
Add comprehensive GitHub Copilot instructions for repository onboarding
2 parents d1d0c3d + ba5f841 commit 9b23dfa

File tree

3 files changed

+1780
-1626
lines changed

3 files changed

+1780
-1626
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Python Data Plotly Predictive Analytics Dashboard
2+
Professional construction project management dashboard built with Python, Plotly, and Dash. Features interactive visualizations, real-time analytics, and automated GitHub Pages deployment.
3+
4+
**ALWAYS follow these instructions exactly. Only fallback to additional search and context gathering if the information in these instructions is incomplete or found to be in error.**
5+
6+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
7+
8+
## Working Effectively
9+
- Bootstrap, build, and test the repository:
10+
- `python --version` -- verify Python 3.8+ is installed
11+
- `pip install pandas numpy plotly dash dash-bootstrap-components` -- takes 40 seconds. NEVER CANCEL. Set timeout to 60+ minutes.
12+
- `cd AI_Dashboard_Implementation/scripts` -- ALWAYS use this directory for main functionality
13+
- `python data_gen.py` -- generates construction project data, takes 3 seconds
14+
- `python viz.py` -- creates dashboard, takes 5 seconds. Choose option 2 for HTML export.
15+
- Full test suite:
16+
- `python validate_monica_ai.py` -- validates system integration, takes 10 seconds
17+
- `python test_dashboard_validation.py` -- comprehensive dashboard validation, takes 60 seconds. NEVER CANCEL. Set timeout to 90+ minutes.
18+
- Run the interactive dashboard:
19+
- ALWAYS run the bootstrapping steps first.
20+
- `cd AI_Dashboard_Implementation/scripts && python viz.py` -- choose option 1 for server mode
21+
- Dashboard available at: http://localhost:8050
22+
- Debug mode: Enabled by default
23+
24+
## Validation
25+
- Always manually validate any new code by generating data and testing dashboard export.
26+
- ALWAYS run through at least one complete end-to-end scenario after making changes:
27+
1. Generate fresh data: `python data_gen.py`
28+
2. Export dashboard: `python viz.py` (option 2)
29+
3. Verify HTML file created in `../outputs/dashboard.html`
30+
4. Test interactive mode: `python viz.py` (option 1) and access http://localhost:8050
31+
- You can build and run the application locally, and the dashboard works in browser preview.
32+
- Always run `python validate_monica_ai.py` and `python test_dashboard_validation.py` before you are done or the CI (.github/workflows/pages.yml) will fail.
33+
34+
## Common tasks
35+
The following are outputs from frequently run commands. Reference them instead of viewing, searching, or running bash commands to save time.
36+
37+
### Repo root
38+
ls -a [repo-root]
39+
.
40+
..
41+
.git
42+
.github
43+
.gitignore
44+
AI_Dashboard_Implementation
45+
AI_Knowledge_Extraction_System
46+
Monica_AI_System
47+
README.md
48+
requirements.txt
49+
requirements_processing.txt
50+
scripts
51+
outputs
52+
data
53+
docs
54+
55+
### Primary working directory
56+
cd AI_Dashboard_Implementation
57+
ls -la
58+
data/
59+
guides/
60+
outputs/
61+
scripts/
62+
63+
### Data generation output
64+
cd AI_Dashboard_Implementation/scripts && python data_gen.py
65+
🏗️ Construction Dashboard Data Generation
66+
📊 Generating projects master data... ✅ Generated 25 projects
67+
🔧 Generating resources data... ✅ Generated 200 resource entries
68+
👥 Generating workload data... ✅ Generated 300 workload entries
69+
💰 Generating budget variance data... ✅ Generated 183 budget tracking entries
70+
📈 Generating project stages data... ✅ Generated 175 project stage entries
71+
📋 Generating project status data... ✅ Generated 1625 daily status entries
72+
✅ Data generation completed successfully!
73+
74+
### Dashboard export output
75+
python viz.py (option 2)
76+
🏗️ Construction Project Management Dashboard
77+
✅ All data files loaded successfully
78+
✅ Dashboard exported to ../outputs/dashboard.html
79+
80+
### pip install requirements.txt
81+
pip install pandas numpy plotly dash dash-bootstrap-components
82+
Installing packages... (takes 40 seconds)
83+
Successfully installed dash-3.2.0 plotly-6.3.0 pandas-2.3.1 numpy-2.3.2 dash-bootstrap-components-2.0.3
84+
85+
## Build and Deployment Timing
86+
- **CRITICAL**: Set appropriate timeouts for all commands. DO NOT use default timeouts.
87+
- **NEVER CANCEL BUILDS OR LONG-RUNNING COMMANDS**.
88+
- Dependencies installation: Takes 40 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
89+
- Data generation: Takes 3 seconds. Safe with default timeout.
90+
- Dashboard creation: Takes 5 seconds. Safe with default timeout.
91+
- Full validation suite: Takes 60 seconds. NEVER CANCEL. Set timeout to 90+ minutes.
92+
- GitHub Actions deployment: Takes 2-3 minutes. NEVER CANCEL. Automatic timeout handling.
93+
94+
## Repository Structure Overview
95+
- **AI_Dashboard_Implementation/**: Main working directory with functional dashboard
96+
- `scripts/data_gen.py`: Generates realistic construction project data (2508 data points)
97+
- `scripts/viz.py`: Creates interactive Dash dashboard with HTML export
98+
- `data/`: Generated CSV files (projects_master.csv, resources.csv, etc.)
99+
- `outputs/`: Generated dashboard.html file for GitHub Pages
100+
- **scripts/**: Legacy dashboard implementations (some have syntax errors)
101+
- **Monica_AI_System/**: AI-powered knowledge processing system
102+
- **docs/**: Documentation and archived project files
103+
- **.github/workflows/pages.yml**: Automated GitHub Pages deployment
104+
105+
## Key Validation Commands
106+
```bash
107+
# Comprehensive system validation
108+
python validate_monica_ai.py # 10 seconds
109+
python test_dashboard_validation.py # 60 seconds - NEVER CANCEL
110+
111+
# Quick validation workflow
112+
cd AI_Dashboard_Implementation/scripts
113+
python data_gen.py # 3 seconds
114+
python viz.py # 5 seconds, choose option 2
115+
ls -la ../outputs/dashboard.html # Verify file exists
116+
```
117+
118+
## Dependency Requirements
119+
```python
120+
# Core requirements (install time: 40 seconds)
121+
pandas>=2.3.1
122+
numpy>=2.3.2
123+
plotly>=6.3.0
124+
dash>=3.2.0
125+
dash-bootstrap-components>=2.0.3
126+
127+
# Additional for full functionality (install time: 10 seconds)
128+
scikit-learn>=1.7.1
129+
scipy>=1.16.1
130+
```
131+
132+
## Development Environment Setup
133+
1. **Python Version**: Requires Python 3.8+ (tested with 3.12.3)
134+
2. **Package Manager**: Uses pip (tested with 24.0)
135+
3. **Virtual Environment**: Recommended but not required
136+
4. **Operating System**: Linux/Ubuntu (GitHub Actions), Windows/macOS supported locally
137+
138+
## Troubleshooting Common Issues
139+
- **Missing outputs directory**: Run `mkdir -p AI_Dashboard_Implementation/outputs`
140+
- **Import errors**: Install missing packages with `pip install [package]`
141+
- **Deprecated API warnings**: Use AI_Dashboard_Implementation scripts (newer versions)
142+
- **Server connection errors**: Check port 8050 availability for interactive mode
143+
144+
## GitHub Pages Deployment
145+
- **Automatic**: Deploys on push to main branch when files in data/, scripts/, outputs/, docs/ change
146+
- **Manual**: Use workflow_dispatch trigger in GitHub Actions
147+
- **Access**: Live site at https://genovese-felipe.github.io/Python-Data-Plotly-Predictive-Analytics-Dashboard/
148+
- **Assets**: Dashboard files copied to docs/assets/dashboards/
149+
150+
## Performance Optimization Notes
151+
- Data generation creates 2508 data points across 6 datasets
152+
- Dashboard HTML output size: ~69KB (compressed interactive format)
153+
- Interactive mode supports real-time updates and filtering
154+
- GitHub Pages deployment includes automatic Jekyll build process

0 commit comments

Comments
 (0)