# System Architecture

## Overview

The system should be built as a web platform with a thin, responsive client and a server-side core for persistence, catalog management, plugin validation, and export generation.

## Main building blocks

### Frontend

- browser-based single-page application
- visual rack editor
- component library browser
- BOM and cable views
- import/export screens

### Backend API

- project CRUD
- component catalog API
- plugin upload and validation
- bill of materials generation
- cable estimation service
- authentication and authorization

### Database

- users
- projects
- rack definitions
- component instances
- cable links
- plugin manifests
- catalog components

### Asset storage

- component `SVG` files
- optional `glTF` assets
- import files
- generated exports such as `CSV` and `PDF`

## Recommended domain model split

### Planning domain

- racks
- placements
- connections
- validation rules

### Catalog domain

- components
- manufacturers
- plugin packs
- pricing metadata

### Output domain

- BOM
- exports
- printable documentation

## Rendering approach

For V1, prefer a 2D editor based on `SVG`.

Reasons:

- precise snap and measurement handling
- easier labeling and overlays
- simpler hit-testing for drag and resize interactions
- lower implementation cost than a full 3D editor

3D can be added later as a secondary visualization layer using `glTF` assets and `Three.js`.

## Plugin ingestion approach

Do not load arbitrary CAD files directly into the editor runtime.

Use a controlled import pipeline:

1. user uploads a plugin package
2. backend validates manifest and metadata
3. backend validates assets and dimensions
4. optional CAD conversion creates internal preview assets
5. approved components become available in the catalog

This keeps the editor stable and the plugin model secure.

## Deployment model

### Public SaaS mode

- hosted centrally
- user accounts and teams
- shared component packs
- subscription or usage-based pricing possible later

### Self-hosted mode

- optional future enterprise offering
- internal catalogs
- private component packs

## Security considerations

- signed or verified plugin packs if third-party distribution is allowed
- strict asset and file-type validation
- no execution of untrusted code in plugins
- server-side permission checks for project access
- rate limits on public endpoints

## Scaling considerations

- stateless API instances
- database-backed persistence
- object storage for assets
- asynchronous jobs for heavy imports and exports

This is enough for an internet-facing product without overengineering the first release.
