Skip to content

Commit d90d0a3

Browse files
sayak-sarkarsayak-sarkar
committed
feat(Reports): add automated report generation commands and update .gitignore
1 parent 9657e8a commit d90d0a3

File tree

7 files changed

+229
-266
lines changed

7 files changed

+229
-266
lines changed

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,15 @@ dist/
3434
*.bundle.css
3535
**/*.bundle.css
3636

37+
# Automated reports and status files (generated, not tracked)
38+
**/automated/health-report.md
39+
**/automated/status-dashboard.md
40+
scripts/reports/automated/
41+
reports/automated/*.md
42+
reports/automated/
43+
!reports/automated/.gitkeep
44+
!reports/automated/templates/
45+
3746
# Vite build cache and temp files
3847
.vite/
3948
**/.vite/

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -234,7 +234,9 @@ npm run backend:logs # View backend logs
234234
| 🏗️ **Architecture Overview** | System design and technical details | [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
235235
| 📡 **API Documentation** | Backend API reference | [API.md](docs/API.md) |
236236
| 🚀 **Deployment Guide** | CI/CD and deployment procedures | [DEPLOYMENT.md](docs/DEPLOYMENT.md) |
237-
| 🔍 **Troubleshooting** | Common issues and solutions | [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |
237+
| � **Health Reports** | Monitoring and status dashboard management | [HEALTH_REPORTS.md](docs/HEALTH_REPORTS.md) |
238+
| 🎛️ **Task Management** | Unified task runner and development workflows | [TASK_MANAGEMENT.md](docs/TASK_MANAGEMENT.md) |
239+
| �🔍 **Troubleshooting** | Common issues and solutions | [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |
238240

239241
</div>
240242

‎docs/HEALTH_REPORTS.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# 📊 Health Reports & Status Dashboard Management
2+
3+
## 🎯 Overview
4+
5+
ThinkRED monorepo uses a **smart tracking approach** for health reports and status dashboards that
6+
balances visibility with repository cleanliness.
7+
8+
## 📁 File Organization
9+
10+
```
11+
reports/
12+
├── automated/
13+
│ ├── README.md # 📋 Directory documentation (tracked)
14+
│ ├── .gitkeep # 📌 Keep directory structure (tracked)
15+
│ ├── health-report.md # 📊 Auto-generated health report (untracked)
16+
│ ├── status-dashboard.md # 📊 Auto-generated status dashboard (untracked)
17+
│ └── templates/
18+
│ ├── .gitkeep # 📌 Keep templates directory (tracked)
19+
│ ├── health-report-template.md # 📋 Report template (tracked)
20+
│ └── status-dashboard-template.md # 📋 Dashboard template (tracked)
21+
├── operational/ # 📋 Manual operational reports (tracked)
22+
├── incidents/ # 📋 Incident reports (tracked)
23+
└── security/ # 📋 Security reports (tracked)
24+
```
25+
26+
## 🚫 Why Auto-Generated Reports Are Untracked
27+
28+
### ❌ Problems with Tracking Auto-Generated Content
29+
30+
1. **Repository Noise**: Frequent automated updates pollute commit history
31+
2. **Merge Conflicts**: Multiple deployments create conflicts with timestamps
32+
3. **Meaningless Diffs**: Performance metric changes create large, irrelevant diffs
33+
4. **False Activity**: Automated commits hide real development progress
34+
5. **CI/CD Complexity**: Requires write access and commit permissions
35+
36+
### ✅ Benefits of Untracked Approach
37+
38+
1. **Clean History**: Only meaningful changes appear in git log
39+
2. **No Conflicts**: Automated systems can't create merge conflicts
40+
3. **Real Insights**: Commit activity reflects actual development work
41+
4. **Simplified CI/CD**: No need for commit permissions in automation
42+
5. **Local Generation**: Developers can generate reports locally when needed
43+
44+
## 🔄 Report Generation
45+
46+
### Automated Generation (CI/CD)
47+
48+
Reports are automatically generated by:
49+
- GitHub Actions workflows
50+
- Deployment scripts
51+
- Monitoring systems
52+
- Health check automation
53+
54+
### Manual Generation
55+
56+
Generate reports locally:
57+
58+
```bash
59+
# Generate health report
60+
npm run reports:health
61+
62+
# Generate status dashboard
63+
npm run reports:status
64+
65+
# Generate all reports
66+
npm run reports:generate
67+
```
68+
69+
### Integration with Task Runner
70+
71+
The unified task runner includes report commands:
72+
73+
```bash
74+
npm run task reports:health # Health metrics
75+
npm run task reports:status # Status dashboard
76+
npm run task reports:generate # All reports
77+
```
78+
79+
## 📋 Templates & Documentation
80+
81+
### Tracked Content (Repository Documentation)
82+
83+
- **Templates**: Structure and variable definitions for reports
84+
- **Documentation**: Explains report purpose, generation, and usage
85+
- **Directory Structure**: Maintains organized layout
86+
- **Integration Guides**: How to integrate with monitoring systems
87+
88+
### Untracked Content (Generated Data)
89+
90+
- **Health Reports**: Current system metrics and analysis
91+
- **Status Dashboards**: Real-time operational status
92+
- **Timestamp Data**: Time-sensitive metrics and measurements
93+
- **Performance Logs**: Historical performance data
94+
95+
## 🎛️ Configuration
96+
97+
### .gitignore Rules
98+
99+
```bash
100+
# Automated reports and status files (generated, not tracked)
101+
**/automated/health-report.md
102+
**/automated/status-dashboard.md
103+
scripts/reports/automated/
104+
reports/automated/*.md
105+
reports/automated/
106+
!reports/automated/.gitkeep
107+
!reports/automated/templates/
108+
```
109+
110+
### Directory Structure Preservation
111+
112+
- `.gitkeep` files maintain empty directories
113+
- `README.md` provides context and usage instructions
114+
- `templates/` directory contains tracked template files
115+
116+
## 🔍 Accessing Current Reports
117+
118+
### Local Development
119+
120+
1. Generate locally: `npm run reports:health`
121+
2. Check deployment logs for latest metrics
122+
3. Access monitoring dashboard directly
123+
124+
### Production Environment
125+
126+
1. View deployment artifacts
127+
2. Check CI/CD pipeline outputs
128+
3. Access monitoring system dashboards
129+
4. Review deployment logs
130+
131+
### Team Collaboration
132+
133+
1. Share significant findings via tracked incident/operational reports
134+
2. Use templates to maintain consistency
135+
3. Reference reports in Pull Request descriptions
136+
4. Document important metrics in committed documentation
137+
138+
## 📊 Report Types
139+
140+
### Health Reports (`health-report.md`)
141+
142+
- System performance metrics
143+
- Security assessment results
144+
- Build and deployment health
145+
- Recommendations and action items
146+
147+
**Template**: `templates/health-report-template.md`
148+
149+
### Status Dashboards (`status-dashboard.md`)
150+
151+
- Real-time system status
152+
- Service availability indicators
153+
- Performance trending
154+
- Quick access links
155+
156+
**Template**: `templates/status-dashboard-template.md`
157+
158+
## 🚀 Migration Guide
159+
160+
### From Tracked to Untracked
161+
162+
1. **Remove from Tracking**: Files removed with `git rm --cached`
163+
2. **Add to .gitignore**: Prevent future tracking
164+
3. **Preserve Templates**: Template files remain tracked
165+
4. **Update Automation**: CI/CD generates reports without committing
166+
167+
### For Existing Workflows
168+
169+
1. **Local Generation**: Use `npm run reports:*` commands
170+
2. **CI Integration**: Reports available in deployment artifacts
171+
3. **Monitoring Access**: Direct dashboard access for real-time data
172+
4. **Documentation**: Significant findings go in tracked reports
173+
174+
## 🎯 Best Practices
175+
176+
### For Developers
177+
178+
- **Generate Locally**: Use task runner commands for current status
179+
- **Check Templates**: Reference templates for report structure
180+
- **Document Issues**: Create tracked reports for significant incidents
181+
- **Review Regularly**: Check generated reports during development
182+
183+
### For CI/CD
184+
185+
- **Generate Automatically**: Include report generation in deployment pipeline
186+
- **Store Artifacts**: Save reports as build artifacts
187+
- **Monitor Health**: Use reports for automated health checks
188+
- **Alert on Issues**: Trigger notifications based on report metrics
189+
190+
### For Team Collaboration
191+
192+
- **Share Insights**: Use tracked reports for important findings
193+
- **Maintain Templates**: Keep templates updated with new metrics
194+
- **Document Decisions**: Track architectural decisions in committed docs
195+
- **Review Patterns**: Regular review of generated reports for trends
196+
197+
---
198+
199+
This approach provides the benefits of automated health monitoring while maintaining a clean,
200+
meaningful git history that focuses on actual development work rather than automated noise.

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@
4545

4646
"security:scan": "npm run task security:scan",
4747
"reports:health": "npm run task reports:health",
48+
"reports:status": "npm run task reports:status",
49+
"reports:generate": "npm run task reports:generate",
4850

4951
"install:all": "npm run install:frontend && npm run install:backend",
5052
"install:frontend": "cd frontend && npm install",

‎reports/automated/health-report.md‎

Lines changed: 0 additions & 119 deletions
This file was deleted.

0 commit comments

Comments
 (0)