Skip to content

Commit 57be272

Browse files
laserpilotlaserpilot
authored
Merge pull request #7 from laserpilot/claude-setup
Adding lots of new features
2 parents 380236c + 88b914d commit 57be272

30 files changed

Lines changed: 27831 additions & 5304 deletions

‎CLAUDE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Build Commands
6+
- `npm run dev` - Start development server
7+
- `npm run build` - Build for production
8+
- `npm run preview` - Preview production build
9+
- `npm run format` - Format code with Prettier
10+
11+
## Code Style Guidelines
12+
- Use ES modules (import/export)
13+
- Format with Prettier (runs via `npm run format`)
14+
- Follow Prettier config: 120 char line width, 2 space indent, double quotes, no semicolons
15+
- Keep functions small and focused on a single responsibility
16+
- Use descriptive variable/function names
17+
- Organize imports: built-ins first, then external packages, then local imports
18+
- Handle errors with try/catch blocks for async operations
19+
- Prefer const over let, avoid var
20+
- Use arrow functions for callbacks and anonymous functions
21+
- Document complex logic with clear comments
22+
- Use camelCase for variables/functions, PascalCase for classes

‎LINKING_GUIDELINES.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Linking Guidelines for Creative Tech Taxonomy
2+
3+
## Overview
4+
This document establishes rules for adding links to taxonomy entries to ensure consistency, authority, and usefulness while avoiding misrepresentation or promotional bias.
5+
6+
## Core Principles
7+
8+
### 1. Authority Over Promotion
9+
- Prefer neutral, authoritative sources over promotional content
10+
- Avoid links that could be seen as endorsements of specific commercial services
11+
- When in doubt, choose comprehensive overviews over specific examples
12+
13+
### 2. Representation Accuracy
14+
- Links should represent the full scope of a topic, not just one perspective
15+
- Avoid linking to examples that users might mistake for "the" authority on a topic
16+
- Multiple links should cover different aspects (official, docs, community, etc.)
17+
18+
## Link Categories & Rules
19+
20+
### Specific Tools/Software/Frameworks
21+
**✅ DO:**
22+
- Official website (primary)
23+
- Official documentation
24+
- GitHub repository (if open source)
25+
- Official community forum/Discord
26+
- Learning resources from the creators
27+
28+
**❌ DON'T:**
29+
- Third-party tutorials (unless officially endorsed)
30+
- Commercial course platforms
31+
- Personal blogs about the tool
32+
- Alternative/competing tools in the same entry
33+
34+
**Example:**
35+
```json
36+
"TouchDesigner": {
37+
"links": {
38+
"Official Website": "https://derivative.ca/",
39+
"Documentation": "https://docs.derivative.ca/",
40+
"Community": "https://forum.derivative.ca/"
41+
}
42+
}
43+
```
44+
45+
### Programming Languages
46+
**✅ DO:**
47+
- Official language website
48+
- Official documentation
49+
- Language specification/standard
50+
- Wikipedia (for historical context)
51+
52+
**❌ DON'T:**
53+
- Learning platforms (Codecademy, etc.)
54+
- Specific IDEs or editors
55+
- Tutorial sites
56+
57+
### Broad Concepts/Fields/Methodologies
58+
**✅ DO:**
59+
- Wikipedia (preferred for general concepts)
60+
- Academic/research institution overviews
61+
- Industry standard organization sites
62+
- Leave empty if no authoritative general source exists
63+
64+
**❌ DON'T:**
65+
- Commercial platforms claiming to represent the field
66+
- Specific examples or implementations
67+
- Personal blogs or opinion pieces
68+
- Startup/company sites claiming authority
69+
70+
**Example:**
71+
```json
72+
"Data Visualization": {
73+
"links": {
74+
"Wikipedia": "https://en.wikipedia.org/wiki/Data_visualization"
75+
}
76+
}
77+
```
78+
79+
### Hardware/Physical Objects
80+
**✅ DO:**
81+
- Manufacturer's official site (if single manufacturer)
82+
- Wikipedia (for categories or standards)
83+
- Industry standards organizations
84+
- Technical specifications
85+
86+
**❌ DON'T:**
87+
- Reseller sites
88+
- Review sites
89+
- Comparison sites
90+
91+
### Historical/Legacy Tools
92+
**✅ DO:**
93+
- Wikipedia (primary choice)
94+
- Archive.org for historical documentation
95+
- Museum or preservation sites
96+
- Original manufacturer sites (if still available)
97+
98+
**❌ DON'T:**
99+
- Modern alternatives claiming to replace them
100+
- Nostalgia or fan sites
101+
- Commercial sites selling legacy versions
102+
103+
### Emerging Technologies/Concepts
104+
**✅ DO:**
105+
- Research institution pages
106+
- Standards body sites
107+
- Wikipedia (if established enough)
108+
- Leave empty if too new/undefined
109+
110+
**❌ DON'T:**
111+
- Startup sites claiming to define the space
112+
- News articles or hype pieces
113+
- Individual research papers (unless foundational)
114+
115+
## Special Cases
116+
117+
### When to Leave Links Empty
118+
- **Very broad concepts** without clear authority (e.g., "creativity")
119+
- **Emerging topics** still being defined
120+
- **Categories that are organizational only** (e.g., "Language Type")
121+
- **Topics where all available links are promotional/biased**
122+
123+
### Multiple Links Strategy
124+
When including multiple links, ensure they serve different purposes:
125+
- **Official** (primary resource)
126+
- **Documentation** (technical reference)
127+
- **Community** (support/discussion)
128+
- **Wikipedia** (neutral overview)
129+
- **GitHub** (source code)
130+
131+
### Link Naming
132+
- Use descriptive names: "Official Website" not "Website"
133+
- Be specific: "API Documentation" not "Docs"
134+
- Indicate content type: "GitHub" not "Code"
135+
- Use consistent naming across entries
136+
137+
## Quality Checklist
138+
139+
Before adding any link, ask:
140+
- [ ] Is this an authoritative source for this topic?
141+
- [ ] Does this represent the topic comprehensively?
142+
- [ ] Could users mistake this for "the" authority when it's just one example?
143+
- [ ] Is this neutral or promotional in nature?
144+
- [ ] Will this link still be relevant in 2-3 years?
145+
- [ ] Does this link serve a different purpose than the others already included?
146+
147+
## Examples by Category
148+
149+
### ✅ Good Examples
150+
```json
151+
"Processing": {
152+
"links": {
153+
"Official Website": "https://processing.org/",
154+
"Documentation": "https://processing.org/reference/",
155+
"GitHub": "https://github.com/processing/processing"
156+
}
157+
}
158+
159+
"Machine Learning": {
160+
"links": {
161+
"Wikipedia": "https://en.wikipedia.org/wiki/Machine_learning"
162+
}
163+
}
164+
165+
"Arduino": {
166+
"links": {
167+
"Official Website": "https://www.arduino.cc/",
168+
"Documentation": "https://docs.arduino.cc/",
169+
"Community": "https://forum.arduino.cc/"
170+
}
171+
}
172+
```
173+
174+
### ❌ Bad Examples
175+
```json
176+
"Creative Coding": {
177+
"links": {
178+
"Awesome Course": "https://creativecoding-course.com/",
179+
"Best Tutorial": "https://johnscodingblog.com/creative-coding"
180+
}
181+
}
182+
183+
"AI in Art": {
184+
"links": {
185+
"ArtAI Startup": "https://artai-platform.com/",
186+
"My AI Art Gallery": "https://myaiart.gallery/"
187+
}
188+
}
189+
```
190+
191+
## Review Process
192+
1. **Draft links** following these guidelines
193+
2. **Review for authority** - are these the best possible sources?
194+
3. **Check for bias** - do any links seem promotional?
195+
4. **Test longevity** - are these likely to remain stable?
196+
5. **Validate representation** - do these links serve the user's need to understand the topic?
197+
198+
---
199+
200+
*These guidelines should be followed for all taxonomy content enhancement to maintain consistency and quality across the entire project.*

‎TAXONOMY_MANAGEMENT.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Taxonomy Management Guide
2+
3+
## Overview
4+
The Creative Tech Taxonomy now uses a **multi-file system** for better maintainability. Individual categories are stored in separate JSON files and merged into a single file for the application.
5+
6+
## Directory Structure
7+
```
8+
taxonomy-data/
9+
├── _metadata.json # Root taxonomy metadata
10+
├── _index.json # Category order and filenames
11+
├── creative-code-frameworks.json # Enhanced with descriptions/links
12+
├── game-engines-and-real-time-3d.json # Ready for enhancement
13+
├── web-and-networking-tools.json
14+
├── sensors-and-interaction-methods.json
15+
├── physical-computing.json
16+
├── display-tech-and-video.json
17+
├── professional-av-tools.json
18+
├── ai-machine-learning.json
19+
├── mobile-technology.json
20+
├── asset-creation.json
21+
├── physical-output-and-digital-fabrication.json
22+
└── uncategorized-tools-and-utilities.json
23+
```
24+
25+
## Available Scripts
26+
27+
### `npm run build:taxonomy`
28+
Merges all category files into `public/Creative_Tech_Taxonomy_data.json`
29+
```bash
30+
npm run build:taxonomy
31+
```
32+
33+
### `npm run extract:categories`
34+
Extracts categories from main file back into separate files
35+
```bash
36+
npm run extract:categories
37+
```
38+
39+
### `npm run dev`
40+
Automatically builds taxonomy then starts dev server
41+
```bash
42+
npm run dev
43+
```
44+
45+
### `npm run build`
46+
Automatically builds taxonomy then builds for production
47+
```bash
48+
npm run build
49+
```
50+
51+
## Workflow for Content Enhancement
52+
53+
### 1. Working on Individual Categories
54+
```bash
55+
# Edit any category file directly
56+
vim taxonomy-data/game-engines-and-real-time-3d.json
57+
58+
# Build and test
59+
npm run build:taxonomy
60+
npm run dev
61+
```
62+
63+
### 2. Adding New Content
64+
1. **Edit the category file** in `taxonomy-data/`
65+
2. **Follow LINKING_GUIDELINES.md** for consistency
66+
3. **Build and test** with `npm run build:taxonomy`
67+
4. **Commit both** the category file and built output
68+
69+
### 3. Collaborative Development
70+
- **Different people** can work on different category files
71+
- **Reduced git conflicts** since files are separate
72+
- **Easier code review** for category-specific changes
73+
- **Clear change tracking** per category
74+
75+
## File Formats
76+
77+
### Category Files
78+
Each category file contains a complete category object:
79+
```json
80+
{
81+
"name": {
82+
"en": "Category Name",
83+
"ja": "日本語名"
84+
},
85+
"description": "Category description",
86+
"tags": ["tag1"],
87+
"links": {
88+
"Wikipedia": "https://en.wikipedia.org/wiki/..."
89+
},
90+
"children": [...]
91+
}
92+
```
93+
94+
### Metadata File (`_metadata.json`)
95+
Root taxonomy information:
96+
```json
97+
{
98+
"name": {"en": "Creative Tech Taxonomy", "ja": "..."},
99+
"description": "Root description",
100+
"tags": [],
101+
"links": {}
102+
}
103+
```
104+
105+
### Index File (`_index.json`)
106+
Category order and filenames:
107+
```json
108+
[
109+
{"name": "Creative Code Frameworks", "filename": "creative-code-frameworks.json", "order": 0},
110+
{"name": "Game Engines and Real-Time 3D", "filename": "game-engines-and-real-time-3d.json", "order": 1}
111+
]
112+
```
113+
114+
## Benefits of This System
115+
116+
### ✅ Maintainability
117+
- **Smaller files** easier to edit and review
118+
- **Clear organization** by topic area
119+
- **Reduced complexity** when working on specific categories
120+
121+
### ✅ Collaboration
122+
- **Multiple contributors** can work simultaneously
123+
- **Fewer git conflicts** on large files
124+
- **Category ownership** possible for subject matter experts
125+
126+
### ✅ Content Quality
127+
- **Focused enhancements** per category following guidelines
128+
- **Easier review process** for category-specific changes
129+
- **Systematic enhancement** across all categories
130+
131+
### ✅ Future-Proofing
132+
- **Potential for lazy loading** individual categories
133+
- **API-ready structure** for dynamic content
134+
- **Easier internationalization** and localization
135+
136+
## Migration Notes
137+
138+
- **All existing content preserved** during extraction
139+
- **No changes to d3 code required** - still loads single file
140+
- **Build process automatic** via npm scripts
141+
- **Backward compatible** with existing workflow
142+
143+
## Best Practices
144+
145+
1. **Always run build** before testing changes
146+
2. **Follow linking guidelines** for consistency
147+
3. **Test locally** before committing
148+
4. **Commit category files** along with built output
149+
5. **Use descriptive commit messages** for category changes
150+
151+
---
152+
153+
*This system makes the taxonomy much more manageable while preserving all existing functionality.*

0 commit comments

Comments
 (0)