Architecture

Languages, Frameworks, Libraries, Services, and APIs

Layer	Technology	Purpose	Integration
Blender Addon	Python (bpy)	Extends Blender’s UI and integrates BVCS tools directly into Blender	Communicates with FastAPI backend through REST API
Backend API	FastAPI (Python)	RESTful backend server that handles authentication, version control logic, merge resolution, and file uploads	Connects to PostgreSQL for metadata and MinIO for file storage
Database	PostgreSQL	Stores user data, project metadata, and snapshot version trees	Accessed via SQLAlchemy ORM inside FastAPI
Object Storage	MinIO	Manages binary files such as .blend and .glb models	Accessed by FastAPI through MinIO Python SDK
Frontend Web App	React + Tailwind CSS + model-viewer	Provides browser-based interface for managing Blender projects, viewing 3D snapshots, and resolving conflicts	Fetches REST data from FastAPI and loads 3D models directly from MinIO
Authentication	JWT (JSON Web Token)	Authenticates both web users and Blender addon users	Tokens issued by FastAPI and stored locally in frontend/addon
DevOps / Deployment	Docker + docker-compose	Containerizes all services for consistent development and deployment	Spins up FastAPI, PostgreSQL, and MinIO together
Optional Services	AWS EC2 / Render / Vercel / Netlify	Hosts backend (EC2/Render) and frontend (Vercel/Netlify)	Enables scalable cloud hosting

---

Package / Build Managers

Component	Build / Package Manager
Frontend (React)	npm
Backend (FastAPI)	uv or pip
Blender Addon	Manual packaging into .zip file for Blender installation
Containerization	docker-compose for orchestration

---

Team Roles

Deployment

Hosting Providers

• Backend (FastAPI) → Hosted on Render or AWS EC2 (Dockerized image)
• Database (PostgreSQL) → Managed via Neon.tech or AWS RDS
• Object Storage (MinIO) → Deployed alongside backend in Docker
• Frontend (React App) → Deployed to Vercel or Netlify

Automation

• Docker Compose automates setup for local and production environments.
• Deployment scripts (docker-compose.prod.yml) handle backend + storage stack.
• GitHub Actions CI/CD may later automate deployment from main branch pushes.

---

Development Environment

• Using Containers (Docker) for development.
  Each developer runs a unified environment with:

  • fastapi backend container
  • postgres database container
  • minio storage container
  • optional local React dev server (npm start)

• Virtual Machines are not used, since Docker provides full isolation.

---

Application Type

This is a Single Page Application (SPA) built with React.

• The frontend dynamically loads pages and data via REST API calls (no full reloads).
• The backend serves JSON responses and handles file uploads.
• The Blender Addon functions as a desktop client that interacts with the same API.

---

URLs (Routes) and REST API Endpoints

Frontend Routes

URL	Page / View	Description
/login	LoginView	User login form
/register	RegisterView	User registration
/dashboard	DashboardView	List of projects and recent activity
/projects/:id	ProjectDetailView	Displays snapshots, branches, and contributors
/projects/:id/merge	MergeConflictResolver	UI for resolving merge conflicts visually

---

Backend REST API Endpoints

Base URL: https://api.bvcs.app

Endpoint	Method	Description	Parameters
/auth/register	POST	Create new user account	{ username, email, password }
/auth/login	POST	Authenticate and return JWT	{ username, password }
/projects/	GET	List user projects	JWT token in header
/projects/{id}	GET	Get project details and version history	{id}
/projects/{id}/snapshot	POST	Upload new .blend snapshot	{file, parent_snapshot}
/projects/{id}/merge	POST	Merge branches or snapshots	{source, target}
/models/{id}/preview	GET	Fetch .glb preview for viewing	{id}

---

Views (Frontend Components)

Component	Description
Header / Navbar	Displays global navigation and account info
DashboardView	Shows list of projects and recent updates
ProjectDetailView	Shows project’s snapshots and branches visually
ModelViewer	Uses <model-viewer> to render .glb files directly in browser
MergeConflictResolver	Displays side-by-side meshes and metadata for comparison
AuthViews (Login/Register)	Handles JWT-based authentication

Each React component is modular and uses Tailwind for responsive styling.

---

Database Schema

users

Column	Type	Description
user_id	SERIAL PK	Unique user identifier
username	TEXT	User’s login name
email	TEXT	User email
password_hash	TEXT	Hashed password
created_at	TIMESTAMP	Account creation time

projects

Column	Type	Description
project_id	SERIAL PK	Unique project ID
name	TEXT	Project name
owner_id	FK → users.user_id	Project owner
created_at	TIMESTAMP	When created

snapshots

Column	Type	Description
snapshot_id	SERIAL PK	Snapshot identifier
project_id	FK → projects.project_id	Linked project
user_id	FK → users.user_id	Uploader
object_key	TEXT	File key in MinIO
timestamp	TIMESTAMP	When snapshot created
parent_snapshot	FK → snapshots.snapshot_id	Enables version tree

merges

Column	Type	Description
merge_id	SERIAL PK	Merge event identifier
project_id	FK → projects.project_id	Related project
source_snapshot	FK → snapshots.snapshot_id	Source branch
target_snapshot	FK → snapshots.snapshot_id	Target branch
conflicts_resolved	BOOLEAN	If manual merge occurred

---

Common Queries

Query	Description
List all user projects	SELECT * FROM projects WHERE owner_id = ?;
Get all snapshots for a project	SELECT * FROM snapshots WHERE project_id = ? ORDER BY timestamp DESC;
Get latest snapshot per user per project	Uses DISTINCT ON (user_id) to get latest version
Detect merge conflicts	Join snapshots on parent_snapshot and compare content hashes
List all contributors to a project	SELECT DISTINCT user_id FROM snapshots WHERE project_id = ?;

---

Blender Addon Architecture (Python + bpy)

Module	Description
bvcs_panel.py	Creates BVCS panel inside Blender's UI (Tools tab)
bvcs_ops.py	Defines Blender operators like “Commit Snapshot” and “Fetch Updates”
bvcs_api.py	Handles communication with FastAPI (via requests)
bvcs_utils.py	Handles metadata, file export, hashing
__init__.py	Registers the addon in Blender

Typical User Flow

1. User logs in → JWT stored locally.
2. Clicks “Commit Snapshot” → addon exports .blend, uploads via FastAPI.
3. FastAPI saves metadata in PostgreSQL and file in MinIO.
4. Web dashboard automatically reflects new version.

---

Merge Conflict Handling (High-Level)

• Snapshots form a directed acyclic graph (DAG).
• Merge occurs when two branches share a common ancestor but diverged.
• Conflicts detected via hash comparison of object data, materials, etc.
• The web frontend provides a visual conflict resolver.
• The Blender addon may help resolve local mesh conflicts before re-upload.

---

State Management

Layer	State Storage
Frontend	React Query + Context API
Backend	Stateless (data in PostgreSQL + MinIO)
Blender Addon	Local config files storing auth tokens and preferences

---

Summary

This system allows Blender users to collaborate on 3D projects like developers collaborate in Git.
By connecting Blender (Python), FastAPI, PostgreSQL, MinIO, and React, BVCS provides:

• Seamless version tracking
• Conflict resolution
• Easy rollback
• Visual history and file previews

This combination of local integration and cloud-based management makes BVCS a scalable, developer-grade solution for 3D artists.

---