Imported from mlvnv93/cad-toolbox (
AGENTS.md). Install upstream withnpx skills add mlvnv93/cad-toolbox. Copyright stays with the author.
CAD Toolbox — Coding Agent Instructions
1. Mission
CAD Toolbox is a low-cost, SEO-first web application for engineers and manufacturers.
The product will initially provide:
- Free browser-based CAD viewing
- STEP/STP file viewing
- Automated engineering drawing generation
- PDF/SVG drawing export
The long-term product will expand toward:
- Drawing QA
- Bulk CAD processing
- Manufacturing RFQ automation
- CAD-to-quote workflows
- API/B2B services
Phase 1 must remain deliberately small and reliable.
Do not expand Phase 1 scope without explicit approval.
2. Phase 1 Target
Target public launch:
24 September 2026
Phase 1 must deliver:
- STEP/STP upload
- Drag-and-drop upload
- File picker
- Browser-based 3D viewing
- Rotate
- Pan
- Zoom
- Fit-to-model
- Front view
- Back view
- Top view
- Bottom view
- Left view
- Right view
- Isometric view
- Shaded rendering
- Edge rendering
- Reset view
- Fullscreen
- Loading/progress state
- Error handling
- Basic mobile warning
- STEP/STP → engineering drawing
- A4/A3 drawing
- Front view
- Top view
- Right view
- Isometric view
- Automatic scale
- Units
- Title block
- Projection symbol
- PDF export
- SVG export
- SEO-ready landing pages
3. Current Architecture
Frontend
Use:
- Next.js
- TypeScript
- React
- App Router
- Tailwind CSS
- Three.js
Browser CAD processing
Use:
- OpenCascade
occt-import-js- WebAssembly
STEP/STP files should preferably be processed in the browser for viewing.
Backend
Use:
- Python
- FastAPI
Drawing generation
Use:
- FreeCAD
- TechDraw
- scripted drawing generation
Infrastructure
Initial architecture:
- Cloudflare Pages for frontend
- Linux VPS/container for CAD processing
- GitHub for source control
- Temporary file storage
Do not introduce additional infrastructure unless it solves a demonstrated problem.
4. Architecture Principle
The system should follow:
User
↓
Cloudflare
↓
Next.js
↓
CAD Viewer
↓
OpenCascade WASM
↓
Three.js
↓
STEP/STP model
For drawing generation:
User
↓
Next.js
↓
FastAPI
↓
Temporary job
↓
FreeCAD + TechDraw
↓
PDF/SVG
↓
User
Keep the viewer and drawing-generation systems loosely coupled.
5. CAD Importer Abstraction
Do not tightly couple the application to one OpenCascade package.
Create an abstraction around CAD importing.
Conceptually:
CadImporter
↓
occt-import-js implementation
This allows the underlying CAD importer to be replaced later without rewriting the viewer.
CAD-specific logic should not be scattered throughout React components.
6. Three.js Rules
Use native Three.js initially.
Do NOT introduce React Three Fiber unless explicitly approved.
The initial viewer should use:
- Scene
- Perspective camera
- WebGL renderer
- OrbitControls
- Lighting
- Grid where useful
- Meshes
- Edge geometry where appropriate
The viewer must support:
- Orbit
- Pan
- Zoom
- Fit
- Standard engineering views
- Isometric view
- Shaded mode
- Edge mode
Keep rendering code separate from UI code.
7. Drawing Generation
Drawing generation is server-side.
Use FreeCAD + TechDraw rather than building a custom CAD drawing engine.
Phase 1 drawing:
- A4
- A3
- Front
- Top
- Right
- Isometric
- Automatic view placement
- Automatic scale
- Units
- Title block
- Projection symbol
- SVG
Basic dimensions may be added only if they can be implemented reliably without delaying launch.
Do not build a custom hidden-line-removal or projection engine in Phase 1.
Do not recreate FreeCAD TechDraw functionality unnecessarily.
8. Features NOT in Phase 1
Do not implement the following unless explicitly approved:
- CAD editing
- Assembly tree
- BOM
- Section planes
- Measurement tools
- Advanced annotations
- GD&T
- Exploded views
- Collaboration
- User accounts
- Subscription management
- Payment processing
- Complex job queues
- Native SLDPRT generation
- Advanced assembly conversion
- Real-time collaboration
The goal is to launch a useful product, not a complete CAD platform.
9. STEP → SLDPRT
Do not implement STEP → SLDPRT in Phase 1.
Native SolidWorks files are proprietary and parametric.
If this feature is investigated later, it must be treated as a separate technical and licensing project.
10. File Security
Uploaded CAD files are untrusted input.
Never:
- Execute uploaded files
- Trust filename extensions
- Trust MIME type alone
- Expose server filesystem paths
- Store user CAD files permanently
- Allow arbitrary filesystem access
Use temporary job directories.
Example:
/tmp/cad-jobs/{job-id}/
Files should be deleted after processing.
Initial limits should be configurable.
Suggested starting limits:
- Maximum STEP/STP size: 50 MB
- Drawing generation timeout: 120 seconds
- Limit concurrent CAD jobs
- Limit jobs per IP
- Delete temporary files after processing
These are starting values and must be tested before production.
11. Backend Isolation
FreeCAD must not have unrestricted access to the server filesystem.
CAD processing should operate inside a controlled temporary environment.
Do not allow user-provided input to become arbitrary shell commands.
Never construct shell commands by blindly concatenating user input.
Validate:
- File type
- File size
- File name
- Job ID
- Processing parameters
12. Error Handling
User-facing errors must be understandable.
Examples:
- "This STEP file could not be opened."
- "This file is larger than the 50 MB limit."
- "The CAD model contains unsupported geometry."
- "Drawing generation timed out."
- "We could not generate the drawing."
- "Your browser does not support the required viewer features."
Never expose:
- Stack traces
- Server filesystem paths
- Internal service names
- Secrets
- Environment variables
- Debug information
Detailed errors may be logged server-side.
13. Performance
Prefer:
- Browser-side STEP processing for viewing
- Web Workers where appropriate
- Lazy loading
- Minimal dependencies
- Efficient Three.js geometry
- Disposal of unused Three.js resources
- Progress indicators
- Graceful handling of large models
Do not optimise prematurely.
Measure first when performance becomes an issue.
14. Dependencies
Before adding a dependency, consider:
- Is it necessary?
- Can an existing dependency solve the problem?
- What licence does it use?
- How large is it?
- Does it increase browser bundle size?
- Does it introduce a new runtime?
- Does it increase infrastructure cost?
- Does it create a security or maintenance burden?
Prefer established open-source dependencies.
Avoid unnecessary dependencies.
Do not introduce commercial CAD SDKs without explicit approval.
15. Technologies NOT to Introduce Without Approval
Do not introduce the following simply because they appear attractive:
- Autodesk Platform Services
- CAD Exchanger SDK
- Commercial CAD kernels
- Commercial conversion APIs
- xeokit
- Redis
- Kubernetes
- Microservice architecture
- Supabase
- Firebase
- Paid queues
- Paid storage
- Paid authentication
- Payment processors
These may become appropriate later.
They are not required for the initial MVP.
16. Database
Do not introduce a database in Phase 1 unless required.
The initial product should work without:
- PostgreSQL
- Supabase
- Firebase
- MongoDB
User accounts, subscriptions and usage tracking can be added after product validation.
17. Job Queue
Do not introduce Redis or a complex queue initially.
Start with a simple controlled processing mechanism.
Target:
- 1–2 concurrent FreeCAD jobs
Upgrade the architecture only when actual demand requires it.
18. Frontend Structure
Prefer a structure similar to:
src/
├── app/
│ ├── page.tsx
│ └── viewer/
│ └── page.tsx
│
├── components/
│ └── cad/
│ ├── CadViewer.tsx
│ ├── CadUploader.tsx
│ ├── CadToolbar.tsx
│ └── LoadingOverlay.tsx
│
└── lib/
└── cad/
├── importer.ts
├── geometry.ts
└── camera.ts
The exact structure can evolve if there is a good reason.
19. Component Responsibilities
CadUploader
Responsible for:
- File picker
- Drag/drop
- File validation
- File size validation
- Loading state
It should not contain Three.js rendering logic.
CadViewer
Responsible for:
- Three.js scene
- Camera
- Renderer
- Controls
- CAD geometry display
- Rendering modes
It should not contain SEO content or backend business logic.
CadToolbar
Responsible for:
- Standard views
- Fit
- Reset
- Shaded/edge mode
- Fullscreen
CAD importer
Responsible for:
- Initialising OpenCascade
- Loading STEP/STP
- Converting CAD geometry into renderable geometry
- Returning structured geometry data
20. TypeScript
Use TypeScript throughout the frontend.
Avoid:
any
unless there is a documented reason.
Prefer:
- Interfaces
- Types
- Explicit return types for complex functions
- Narrow error handling
- Typed API responses
CAD geometry types should be defined centrally.
21. React Rules
Keep React components reasonably small.
Avoid giant components containing:
- UI
- Three.js
- file parsing
- API calls
- business logic
Separate concerns.
Use React state for UI state.
Keep Three.js mutable objects in appropriate refs rather than triggering unnecessary React renders.
22. WebAssembly Rules
OpenCascade WASM is a critical part of the application.
Treat WASM loading as asynchronous.
Handle:
- Initialisation
- Loading state
- Failure
- Unsupported browser
- Worker lifecycle
- Memory cleanup where applicable
Do not assume the WASM module is immediately available during server-side rendering.
CAD viewer code must be client-side where required.
23. Next.js Rules
The application uses the Next.js App Router.
CAD viewer components that depend on:
window- WebGL
- Three.js
- WebAssembly
must be treated as client-side functionality.
Avoid accidentally executing browser-only code during server rendering.
24. SEO
SEO is a major product acquisition channel.
The website should eventually contain pages targeting searches such as:
- STEP viewer
- STP viewer
- CAD viewer
- online CAD viewer
- STEP file viewer
- STEP to PDF
- STEP to drawing
- engineering drawing generator
- 3-view drawing generator
- CAD drawing generator
- CNC drawing generator
Do not generate hundreds of low-quality SEO pages automatically.
Each page must provide genuine utility.
25. Product Funnel
The core funnel is:
Google
↓
Free CAD tool
↓
Upload STEP
↓
View model
↓
Generate drawing
↓
Download PDF/SVG
↓
Advanced tools
↓
Paid user
The free viewer is primarily an acquisition mechanism.
The long-term commercial value comes from:
- Drawing automation
- Drawing QA
- Manufacturing workflows
- RFQ automation
- Bulk processing
- API/B2B
26. Analytics
Track meaningful product events rather than only pageviews.
Important events include:
- Page viewed
- Viewer opened
- File selected
- File loaded
- File load failed
- Drawing generation requested
- Drawing generated
- Drawing failed
- PDF downloaded
- SVG downloaded
The most important funnel is:
CAD files opened
↓
Drawings generated
↓
Downloads
↓
Paid conversion
Do not optimise purely for traffic.
27. Cost Control
This is a low-cost startup project.
Every technical decision should consider operating cost.
Prefer:
- Free/open-source software
- Browser processing
- Small VPS
- Static frontend hosting
- Temporary storage
- Minimal infrastructure
Do not add paid infrastructure without demonstrating why it is required.
28. Licensing
Maintain awareness of the licences of:
- OpenCascade
- occt-import-js
- Three.js
- FreeCAD
- TechDraw
- All future dependencies
When adding a dependency:
- Identify its licence.
- Check compatibility.
- Record it where appropriate.
- Avoid copying proprietary source code.
- Do not redistribute software in a way that violates its licence.
Maintain:
docs/licensing.md
when the project becomes sufficiently mature.
29. Git
Use small, logical commits.
Good examples:
feat: add CAD viewer shell
feat: load STEP files with OpenCascade
feat: add standard camera views
feat: add drawing generation endpoint
fix: dispose Three.js geometry after model replacement
Do not make giant commits containing unrelated changes.
Never commit:
.env- secrets
- uploaded CAD files
- generated PDFs
- generated SVGs
- temporary processing files
- unnecessary large binaries
30. Environment Variables
Secrets and environment-specific values must use environment variables.
Never hard-code:
- API keys
- passwords
- tokens
- VPS credentials
- database credentials
Never commit production secrets.
31. Testing
Before considering a feature complete:
- Run TypeScript checks
- Run lint
- Run relevant tests
- Build the application where practical
- Test error conditions
CAD processing should eventually be tested against a fixture set containing:
- Simple block
- Cylinder
- Bracket
- Plate
- Complex mechanical part
- Large model
- Invalid STEP
- Empty/invalid file
- Unsupported geometry
32. CAD Test Fixtures
Test CAD files should be stored separately from user uploads.
Use:
tests/fixtures/
Do not commit proprietary customer CAD files.
Only use:
- Public-domain files
- Openly licensed files
- Internally generated test geometry
- Files for which we have permission
33. Mobile
Phase 1 is desktop-first.
The viewer should still provide a usable mobile experience where practical.
If the device is unsuitable for large CAD models, provide a clear warning rather than allowing the application to fail silently.
34. Accessibility
Important controls should have:
- Accessible labels
- Keyboard focus where practical
- Useful button names
- Visible state changes
Do not rely exclusively on colour to communicate status.
35. UI Design
The interface should feel like an engineering tool.
Priorities:
- Clear
- Professional
- Fast
- Minimal
- Trustworthy
Avoid unnecessary animation.
Avoid excessive gradients and decorative UI.
The CAD model should be the visual focus.
36. Major Architecture Changes
Before making a major architectural change, identify:
- Why the change is needed
- What problem it solves
- Which files/components are affected
- Implementation cost
- Operational cost
- Licensing implications
- Whether the change can be reversed
Do not silently replace the agreed architecture.
If the change is not required for the current task, prefer the existing architecture.
37. Agent Behaviour
Coding agents should:
- Read this file before making significant changes.
- Inspect existing code before creating new code.
- Reuse existing components where appropriate.
- Avoid unnecessary rewrites.
- Keep changes focused.
- Explain significant trade-offs.
- Preserve working functionality.
- Prefer reversible decisions.
- Prefer low-cost solutions.
- Test before declaring a task complete.
If blocked, diagnose the actual problem first.
Do not replace the architecture merely because an implementation is difficult.
38. Decision Priority
When several technical options are available, prioritise:
- Reliability
- Simplicity
- Low implementation cost
- Low operating cost
- Licensing compatibility
- Security
- Performance
- Maintainability
- Future extensibility
Do not choose a technology because it is fashionable.
Choose the simplest solution that can realistically support the first 1,000 users.
39. Current Build Status
Phase:
Phase 1 — MVP
Target launch:
24 September 2026
Current status:
[x] Windows development environment
[x] WSL2 / Ubuntu
[x] VS Code
[x] Git
[x] Node.js
[x] pnpm
[x] Next.js project created
[ ] CAD Toolbox homepage
[ ] Three.js viewer
[ ] OpenCascade STEP import
[ ] Standard camera views
[ ] Upload UX
[ ] FreeCAD installation
[ ] TechDraw generation
[ ] A4/A3 templates
[ ] PDF/SVG export
[ ] FastAPI endpoint
[ ] Frontend/backend integration
[ ] File security limits
[ ] SEO pages
[ ] Analytics
[ ] CAD test suite
[ ] Production deployment
[ ] Public launch
Update this section as major milestones are completed.
40. Golden Rule
Do not overbuild.
The objective is to get a reliable CAD Toolbox MVP into users' hands quickly.
Build:
Viewer
+
STEP import
+
Drawing generation
+
PDF/SVG
+
SEO
Then measure actual usage.
Only build additional infrastructure or features when real user demand justifies them.