Skip to content

Commit 6956d39

Browse files
kvnlooclaude
kvnloo
and
claude
committed
feat: Comprehensive 3D visualization improvements, documentation reorganization, and open source foundation
## 🎨 Visual & Rendering Improvements ### New 3D Components - **Grass Component** (components/Grass.tsx): Realistic grass rendering with 1500 instanced blades per court, wind animation, and color variation - **Clay Court Effects** (components/ClayCourtEffect.tsx): Procedural clay texture with normal mapping, 150 dust particles per court - **Court Textures** (src/utils/courtTextures.ts): Procedural wood grain and concrete textures with normal mapping - **Building Interiors**: BMSControlRoom, ParkingLot, ReceptionArea components with detailed 3D architecture ### ThreeScene Enhancements - Fixed court labeling system (removed text from surfaces, added floating 3D labels) - Integrated grass rendering for all 6 grass courts - Added clay particle effects for courts 6-11 - Implemented wood grain textures for wood courts (18-23) - Added concrete textures for hard courts (0-5) - Proper court surface differentiation with realistic materials ### Visual Quality - Performance-optimized instanced rendering (60 FPS maintained) - Realistic materials with PBR (physically-based rendering) - Procedural textures reduce bundle size - Normal mapping adds depth without geometry cost ## 📚 Documentation Infrastructure Overhaul ### Dual Documentation System Created separation between facility documentation (stakeholder-facing) and developer documentation (code-focused): **docs/** - Facility Documentation: - concepts/ - APEX vision and business model - architecture/ - Building design and digital twin architecture - specifications/ - Technical specifications and materials - operations/ - Future operational procedures - research/ - Design research and analysis - business/ - Future business planning - archive/ - Historical documentation **claudedocs/** - Developer Documentation: - 01-architecture/ - Court layouts and 3D labeling system - 02-implementation-guides/ - Feature implementation (grass, clay, textures) - 03-testing-quality/ - TDD methodology and integration tests - 04-monitoring-operations/ - Performance testing and monitoring - 05-workflows/ - Deployment and rollback procedures - 06-research/ - Technical research (animations, image-to-3D pipeline) - 07-features/ - Complete feature inventory and roadmap - 08-stories/ - Implementation stories - 09-milestones/ - Project milestones ### Documentation Files Created - 130+ new markdown files with comprehensive technical and facility documentation - Master navigation READMEs for all categories - Quick reference guides - Role-based navigation (developers, stakeholders, contributors) ## 🌐 Open Source Foundation ### Multi-License Strategy - **MIT License** - Source code (maximum adoption) - **CC-BY-SA 4.0** - Designs, models, documentation (share-alike for improvements) - Clear attribution and commercial use guidelines ### Governance & Community - CONTRIBUTING.md - Contribution guidelines for code, designs, and documentation - CODE_OF_CONDUCT.md - Community standards (Contributor Covenant) - GOVERNANCE.md - Project governance structure (benevolent dictatorship) - DIGITAL_TWIN_ROADMAP.md - 5-phase roadmap from portfolio to full digital twin ### Open Source Documentation - Contributor quick start guide - Open source setup summary - License recommendations with rationale - RFC (Request for Comments) process for major changes ## 🧪 Testing & Quality Infrastructure ### Test Setup - Vitest configuration (vite.config.ts) - React Testing Library integration - Test setup with jsdom environment (tests/setup.ts) - Example tests: QualityBadge (TDD example), Grass rendering ### Performance Monitoring - Performance baseline capture script (scripts/performance-baseline.js) - Performance regression testing (scripts/performance-test.js) - Bundle size analysis (scripts/bundle-size.js) - Monitoring documentation and quick references ### Quality Assurance - Comprehensive verification checklists - Integration test specifications - Manual testing procedures - Performance budgets and thresholds ## 🚀 Deployment & Infrastructure ### GitHub Actions Improvements - Added enhance/3D branch deployment to GitHub Pages - Branch preview at /ace/enhance-3D/ path - Concurrent deployments: main (root), dev (/dev/), enhance/3D (/enhance-3D/) - VITE_BASE_PATH configuration per branch ### Development Tools - Emergency rollback scripts (scripts/rollback-to-snapshot.sh) - State verification tools (scripts/verify-state.sh) - Snapshot creation for safe experimentation - Dev server monitoring and error tracking ## 📊 Research & Planning ### Image-to-3D Pipeline - Comprehensive research on AI image analysis workflows - Vision AI comparison (Claude, GPT-4V, Gemini) - Metadata schema design for architectural features - Feature tracking and gap analysis methodology - SuperClaude integration patterns ### Animation Research - People animation best practices for React Three Fiber - Mixamo integration guide - Performance optimization strategies (LOD, VAT) - Tennis-specific animation recommendations ### Digital Twin Architecture - 5-phase roadmap (30 months) - Technical stack recommendations - IoT integration strategy - Multi-facility federation design ## 🎯 Impact Summary ### Code Changes - 6 new React components (1,800+ lines) - 1 new utility module (courtTextures) - Enhanced ThreeScene with all visual improvements - Test infrastructure with working examples ### Documentation - 130+ markdown files (comprehensive technical docs) - Organized into 16 categories - Dual documentation system (facility + developer) - Open source foundation complete ### Visual Quality - All 24 tennis courts now have realistic surfaces - Grass courts: animated grass with wind effects - Clay courts: granular texture with dust particles - Wood courts: realistic wood grain with normal mapping - Hard courts: concrete texture with professional finish - Professional 3D labels (no text on surfaces) ### Performance - Maintained 60 FPS target - Optimized instanced rendering - Procedural textures reduce bundle size - Performance monitoring infrastructure in place ### Infrastructure - Multi-branch deployment (main, dev, enhance/3D) - Testing framework operational - Performance monitoring active - Open source contribution ready ## 🔗 Related Documentation - Implementation details: claudedocs/02-implementation-guides/ - Visual improvements: claudedocs/01-architecture/ - Testing setup: claudedocs/03-testing-quality/ - Open source guide: docs/OPEN_SOURCE_GUIDE.md - Digital twin roadmap: docs/DIGITAL_TWIN_ROADMAP.md - Feature roadmap: claudedocs/07-features/FEATURE_ROADMAP.md ## 🎓 Technical Debt Addressed - Fixed court labeling (removed surface text, added 3D labels) - Restored missing visual elements (grass, clay, textures) - Organized scattered documentation - Established testing infrastructure - Created performance monitoring baseline - Implemented proper open source foundation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent e80d8ee commit 6956d39

147 files changed

Lines changed: 53444 additions & 148 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/DEPLOYMENT.md‎

Lines changed: 8 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,13 @@
1-
# GitHub Pages Deployment Guide
1+
# Deployment Guide
22

3-
This project uses GitHub Actions to automatically build and deploy to GitHub Pages from both `main` and `dev` branches.
3+
**Note:** This file has been moved to the centralized documentation.
44

5-
## Setup Instructions
5+
Please refer to: [`/claudedocs/05-workflows/DEPLOYMENT.md`](../claudedocs/05-workflows/DEPLOYMENT.md)
66

7-
### 1. Enable GitHub Pages
7+
---
88

9-
1. Go to your repository settings
10-
2. Navigate to **Pages** (under "Code and automation")
11-
3. Under **Source**, select **GitHub Actions**
9+
## Quick Links
1210

13-
### 2. Deployment Strategy
14-
15-
The workflow automatically:
16-
- Builds the `main` branch and deploys to the root path (`/`)
17-
- Builds the `dev` branch and deploys to `/dev/` path
18-
- Combines both builds into a single deployment
19-
20-
### 3. Triggering Deployments
21-
22-
Deployments are triggered automatically when you push to either:
23-
- `main` branch → Updates the production site at `https://<username>.github.io/<repo>/`
24-
- `dev` branch → Updates the dev site at `https://<username>.github.io/<repo>/dev/`
25-
26-
Both builds happen together regardless of which branch triggered the workflow, ensuring both sites are always in sync with their respective branches.
27-
28-
## URLs
29-
30-
After deployment, your sites will be available at:
31-
32-
- **Production (main)**: `https://<username>.github.io/<repo>/`
33-
- **Development (dev)**: `https://<username>.github.io/<repo>/dev/`
34-
35-
Replace `<username>` with your GitHub username and `<repo>` with your repository name.
36-
37-
## How It Works
38-
39-
1. **Build Phase**:
40-
- Checks out and builds the `main` branch with base path `/`
41-
- Checks out and builds the `dev` branch with base path `/dev/`
42-
- Combines both builds into a single deployment directory
43-
44-
2. **Deploy Phase**:
45-
- Uploads the combined artifact to GitHub Pages
46-
- GitHub Pages serves both sites from the same deployment
47-
48-
## Monitoring Deployments
49-
50-
- Go to the **Actions** tab in your repository
51-
- View the workflow runs for "Build and Deploy to GitHub Pages"
52-
- Each run shows the build and deployment status
53-
54-
## Troubleshooting
55-
56-
### Deployment fails with "Artifact not found"
57-
- Ensure the workflow has completed the build phase successfully
58-
- Check the build logs for any compilation errors
59-
60-
### 404 errors on deployed site
61-
- Verify that GitHub Pages is enabled in repository settings
62-
- Confirm the source is set to "GitHub Actions"
63-
- Wait a few minutes after deployment completes
64-
65-
### Assets not loading correctly
66-
- Check that `vite.config.ts` correctly sets the base path
67-
- Verify the VITE_BASE_PATH environment variable in the workflow
68-
69-
## Local Testing
70-
71-
To test the builds locally before deploying:
72-
73-
```bash
74-
# Test main branch build
75-
VITE_BASE_PATH=/ npm run build
76-
npm run preview
77-
78-
# Test dev branch build
79-
VITE_BASE_PATH=/dev/ npm run build
80-
npm run preview
81-
```
82-
83-
## Customization
84-
85-
To modify deployment behavior, edit `.github/workflows/deploy.yml`:
86-
87-
- Change trigger branches in the `on.push.branches` section
88-
- Modify base paths in the `VITE_BASE_PATH` environment variables
89-
- Adjust Node.js version in the `Setup Node.js` step
11+
- **Full Deployment Guide:** [claudedocs/05-workflows/DEPLOYMENT.md](../claudedocs/05-workflows/DEPLOYMENT.md)
12+
- **Rollback Procedures:** [claudedocs/05-workflows/ROLLBACK_PROCEDURES.md](../claudedocs/05-workflows/ROLLBACK_PROCEDURES.md)
13+
- **All Documentation:** [claudedocs/README.md](../claudedocs/README.md)

‎.github/workflows/deploy.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ on:
55
branches:
66
- main
77
- dev
8+
- enhance/3D
89

910
permissions:
1011
contents: read
@@ -67,6 +68,28 @@ jobs:
6768
mkdir -p deploy/dev
6869
cp -r dist/* deploy/dev/
6970
71+
- name: Checkout enhance/3D branch
72+
uses: actions/checkout@v4
73+
with:
74+
ref: enhance/3D
75+
clean: false
76+
77+
- name: Clean previous build
78+
run: rm -rf dist node_modules
79+
80+
- name: Install dependencies for enhance/3D
81+
run: npm install
82+
83+
- name: Build enhance/3D branch
84+
run: npm run build
85+
env:
86+
VITE_BASE_PATH: '/ace/enhance-3D/'
87+
88+
- name: Copy enhance/3D build to /enhance-3D subdirectory
89+
run: |
90+
mkdir -p deploy/enhance-3D
91+
cp -r dist/* deploy/enhance-3D/
92+
7093
- name: Upload combined artifact
7194
uses: actions/upload-pages-artifact@v3
7295
with:

‎.snapshots/snapshot-log.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
snapshot-20251121-191540|final-test|b8f476e56fd5a0c0b3bf136ec5486f4a579817c4|e80d8eed9ed23e6ba9b11ea3c66b601d2eb2c60d|enhance/3D|Fri Nov 21 07:15:41 PM CST 2025

‎LICENSE‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2025 Kevin Rajan
3+
Copyright (c) 2025 LawnTech Dynamics (Kevin Rajan)
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,22 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1919
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
2020
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
2121
SOFTWARE.
22+
23+
---
24+
25+
SCOPE:
26+
This MIT License applies to all source code, algorithms, and software
27+
components in this repository, including:
28+
29+
- TypeScript/JavaScript source code (*.ts, *.tsx, *.js, *.jsx)
30+
- Configuration files and build scripts
31+
- Test suites and testing utilities
32+
- Utility functions and helper libraries
33+
- Algorithm implementations (grass growth, energy optimization, etc.)
34+
35+
For other asset types, see:
36+
- LICENSE-DESIGNS: Facility designs and blueprints (CC-BY-SA 4.0)
37+
- LICENSE-MODELS: 3D models and visualizations (CC-BY-SA 4.0)
38+
- LICENSE-DOCS: Documentation and guides (CC-BY-SA 4.0)
39+
40+
See docs/LICENSE_RECOMMENDATIONS.md for complete licensing rationale.

‎LICENSE-DESIGNS‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
Creative Commons Attribution-ShareAlike 4.0 International License
2+
3+
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
4+
International License.
5+
6+
Copyright (c) 2025 LawnTech Dynamics
7+
8+
COVERED ASSETS:
9+
- Facility floor plans and layouts (docs/designs/, docs/blueprint.md)
10+
- Spatial optimization specifications
11+
- Safety compliance documentation
12+
- Architectural drawings and blueprints
13+
- CAD files and technical specifications
14+
15+
YOU ARE FREE TO:
16+
- Share: copy and redistribute the material in any medium or format
17+
- Adapt: remix, transform, and build upon the material for any purpose,
18+
even commercially
19+
20+
UNDER THE FOLLOWING TERMS:
21+
- Attribution: You must give appropriate credit, provide a link to the
22+
license, and indicate if changes were made. You may do so in any
23+
reasonable manner, but not in any way that suggests the licensor
24+
endorses you or your use.
25+
26+
- ShareAlike: If you remix, transform, or build upon the material, you
27+
must distribute your contributions under the same license as the original.
28+
29+
- No additional restrictions: You may not apply legal terms or technological
30+
measures that legally restrict others from doing anything the license permits.
31+
32+
NOTICES:
33+
You do not have to comply with the license for elements of the material in
34+
the public domain or where your use is permitted by an applicable exception
35+
or limitation.
36+
37+
No warranties are given. The license may not give you all of the permissions
38+
necessary for your intended use. For example, other rights such as publicity,
39+
privacy, or moral rights may limit how you use the material.
40+
41+
Full License Text:
42+
https://creativecommons.org/licenses/by-sa/4.0/legalcode
43+
44+
Human-Readable Summary:
45+
https://creativecommons.org/licenses/by-sa/4.0/
46+
47+
---
48+
49+
ATTRIBUTION EXAMPLES:
50+
51+
For facility designs:
52+
"Based on LawnTech Dynamics facility design by Kevin Rajan,
53+
licensed under CC-BY-SA 4.0: https://github.com/kvnloo/ace"
54+
55+
For derivative designs:
56+
"Modified from LawnTech Dynamics facility design, original by Kevin Rajan,
57+
licensed under CC-BY-SA 4.0: https://github.com/kvnloo/ace"
58+
59+
For commercial facilities:
60+
"Facility layout based on LawnTech Dynamics open source design
61+
(CC-BY-SA 4.0): https://github.com/kvnloo/ace"

‎LICENSE-DOCS‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
Creative Commons Attribution-ShareAlike 4.0 International License
2+
3+
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
4+
International License.
5+
6+
Copyright (c) 2025 LawnTech Dynamics
7+
8+
COVERED ASSETS:
9+
- User guides and tutorials (docs/*, claudedocs/*)
10+
- Technical specifications and documentation
11+
- API documentation and code comments
12+
- Contributing guidelines and governance documents
13+
- Research papers and technical reports
14+
- README files and wiki content
15+
- Design rationale and architecture decision records
16+
17+
YOU ARE FREE TO:
18+
- Share: copy and redistribute the material in any medium or format
19+
- Adapt: remix, transform, and build upon the material for any purpose,
20+
even commercially
21+
22+
UNDER THE FOLLOWING TERMS:
23+
- Attribution: You must give appropriate credit, provide a link to the
24+
license, and indicate if changes were made. You may do so in any
25+
reasonable manner, but not in any way that suggests the licensor
26+
endorses you or your use.
27+
28+
- ShareAlike: If you remix, transform, or build upon the material, you
29+
must distribute your contributions under the same license as the original.
30+
31+
- No additional restrictions: You may not apply legal terms or technological
32+
measures that legally restrict others from doing anything the license permits.
33+
34+
NOTICES:
35+
You do not have to comply with the license for elements of the material in
36+
the public domain or where your use is permitted by an applicable exception
37+
or limitation.
38+
39+
No warranties are given. The license may not give you all of the permissions
40+
necessary for your intended use. For example, other rights such as publicity,
41+
privacy, or moral rights may limit how you use the material.
42+
43+
Full License Text:
44+
https://creativecommons.org/licenses/by-sa/4.0/legalcode
45+
46+
Human-Readable Summary:
47+
https://creativecommons.org/licenses/by-sa/4.0/
48+
49+
---
50+
51+
TRANSLATION POLICY:
52+
Translations of documentation are welcome and encouraged! Translated
53+
documentation must also be licensed under CC-BY-SA 4.0 and include
54+
attribution to the original work.
55+
56+
ATTRIBUTION EXAMPLES:
57+
58+
For documentation:
59+
"Based on LawnTech Dynamics documentation by Kevin Rajan,
60+
licensed under CC-BY-SA 4.0: https://github.com/kvnloo/ace"
61+
62+
For derivative guides:
63+
"Modified from LawnTech Dynamics user guide, original by Kevin Rajan,
64+
licensed under CC-BY-SA 4.0: https://github.com/kvnloo/ace"
65+
66+
For translations:
67+
"Translated from LawnTech Dynamics documentation (English original),
68+
licensed under CC-BY-SA 4.0: https://github.com/kvnloo/ace"
69+
70+
For academic citations:
71+
Rajan, K. (2025). LawnTech Dynamics: Autonomous Indoor Sports Facility.
72+
GitHub. https://github.com/kvnloo/ace (CC-BY-SA 4.0)

‎LICENSE-MODELS‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Creative Commons Attribution-ShareAlike 4.0 International License
2+
3+
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
4+
International License.
5+
6+
Copyright (c) 2025 LawnTech Dynamics
7+
8+
COVERED ASSETS:
9+
- 3D facility models and visualizations (components/ThreeScene.tsx)
10+
- Court surface textures and materials (src/utils/courtTextures.ts)
11+
- Equipment 3D models
12+
- Interactive scene components
13+
- Architectural 3D representations
14+
- Rendered visualizations and screenshots
15+
16+
YOU ARE FREE TO:
17+
- Share: copy and redistribute the material in any medium or format
18+
- Adapt: remix, transform, and build upon the material for any purpose,
19+
even commercially
20+
21+
UNDER THE FOLLOWING TERMS:
22+
- Attribution: You must give appropriate credit, provide a link to the
23+
license, and indicate if changes were made. You may do so in any
24+
reasonable manner, but not in any way that suggests the licensor
25+
endorses you or your use.
26+
27+
- ShareAlike: If you remix, transform, or build upon the material, you
28+
must distribute your contributions under the same license as the original.
29+
30+
- No additional restrictions: You may not apply legal terms or technological
31+
measures that legally restrict others from doing anything the license permits.
32+
33+
NOTICES:
34+
You do not have to comply with the license for elements of the material in
35+
the public domain or where your use is permitted by an applicable exception
36+
or limitation.
37+
38+
No warranties are given. The license may not give you all of the permissions
39+
necessary for your intended use. For example, other rights such as publicity,
40+
privacy, or moral rights may limit how you use the material.
41+
42+
Full License Text:
43+
https://creativecommons.org/licenses/by-sa/4.0/legalcode
44+
45+
Human-Readable Summary:
46+
https://creativecommons.org/licenses/by-sa/4.0/
47+
48+
---
49+
50+
TECHNICAL NOTE:
51+
Shader code and rendering algorithms may also be available under the MIT
52+
License (see main LICENSE file). The visual output and 3D models themselves
53+
remain under CC-BY-SA 4.0.
54+
55+
ATTRIBUTION EXAMPLES:
56+
57+
For 3D models:
58+
"3D facility model from LawnTech Dynamics by Kevin Rajan,
59+
licensed under CC-BY-SA 4.0: https://github.com/kvnloo/ace"
60+
61+
For derivative models:
62+
"Modified 3D model based on LawnTech Dynamics, original by Kevin Rajan,
63+
licensed under CC-BY-SA 4.0: https://github.com/kvnloo/ace"
64+
65+
For screenshots/renders:
66+
"Visualization based on LawnTech Dynamics 3D models
67+
(CC-BY-SA 4.0): https://github.com/kvnloo/ace"

0 commit comments

Comments
 (0)