Parascope

A node-based engineering calculation platform for agile teams and hobbyists.

---

Parascope allows users to define complex engineering models using a visual graph interface, where nodes represent parameters, mathematical functions, or entire nested calculation sheets.

🚀 Features

• Visual Graph Editor: Intuitive node-based interface built with Rete.js for defining complex engineering logic.
• Python-Powered Calculations: Secure backend execution engine runs Python code with support for numpy, scipy, and networkx.
• Nested Sheets: Create reusable calculation modules (sheets) and import them into other sheets as single nodes, enabling modular system design.
• Advanced Trade Studies: Perform parameter sweeps and visualize results with interactive Line, Bar, Scatter, and Timeline charts.
• AI Assistance: Generate function logic from natural language using Google Gemini, OpenAI, or AWS Bedrock.
• Version Control: Create immutable snapshots of calculation sheets and manage default versions for reliable sharing and design stabilization.
• Offline Execution: Export sheets as standalone Python scripts that can be run offline using the parascope-runtime package.
• Secure Runtime: Sandboxed execution environment using RestrictedPython with configurable module allow-lists.
• High Performance: Optimized worker pool with module preloading and non-blocking architecture for responsive UI interactions.
• Real-time Evaluation: Instant feedback on calculation results as you modify the graph.
• Engineering Examples: Comes pre-seeded with examples like the Tsiolkovsky Rocket Equation, Aerodynamic Drag, and SSTO Feasibility checks.

🛠️ Tech Stack

Frontend

• Framework: React 19 + TypeScript + Vite
• Graph Library: Rete.js 2.0 (Classic Preset) + elkjs (Auto-layout)
• Visualization: Apache ECharts (2D/3D Charts)
• Styling: CSS Modules, Lucide React (Icons)
• Math Rendering: KaTeX
• Node.js: >= 24
• Package Manager: pnpm

Backend

• Framework: FastAPI (Python 3.12)
• Execution: RestrictedPython (Secure Sandbox)
• Scientific Stack: NumPy, SciPy, NetworkX
• AI Integration: google-genai, openai, boto3
• Database: PostgreSQL + asyncpg
• ORM: SQLAlchemy + Alembic
• Runtime: Docker / Docker Compose
• Package Manager: uv

🏁 Quick Start

The easiest way to run Parascope is using Docker Compose.

1. Clone the repository:

   git clone https://github.com/tokoro10g/parascope.git
   cd parascope

2. Configure the environment: Create a .env file from the example.

   cp .env.example .env

3. Start the application:

   docker compose up --build

4. Access the application:

   • Frontend: Open http://localhost:3000 in your browser.
   • Backend API Docs: Open http://localhost:8000/docs.

🚢 Production Deployment

For production environments, Parascope provides a optimized Docker configuration using Nginx to serve the frontend and proxy requests to the backend.

docker compose -f docker-compose.prod.yml up --build -d

This configuration:

• Uses a multi-stage build for the frontend to produce a lightweight static bundle.
• Serves the frontend via Nginx on port 80.
• Proxies API requests internally from Nginx to the backend service.
• Runs the backend in a production-optimized mode without hot-reloading.

🐍 Offline Execution & Generated Scripts

Parascope allows you to export your calculation sheets as standalone Python scripts. These scripts can be run offline without the Parascope server by using the parascope-runtime package.

Running Generated Scripts

1. Export the script: Use the "Generate Script" feature in the Parascope UI.
2. Install the runtime:

   pip install ./packages/parascope-runtime

3. Run your script:

   python your_exported_script.py

The generated code includes all necessary logic, including nested sheets, which are reconstructed as Python classes.

📂 Project Structure

parascope/
├── .github/            # CI/CD workflows
├── backend/            # FastAPI application
│   ├── src/
│   │   ├── api/        # API Routes
│   │   ├── core/       # Execution engine & config
│   │   ├── models/     # Database models
│   │   └── schemas/    # Pydantic schemas
│   └── tests/          # Pytest suite
├── frontend/           # React application
│   ├── src/
│   │   ├── core/       # API clients, Rete logic, and contexts
│   │   ├── features/   # Domain-specific components and hooks
│   │   ├── pages/      # Route-level page components
│   │   ├── components/ # Shared UI primitives
│   │   └── styles/     # Global CSS and themes
│   └── vite.config.ts  # Configured with `@/` path aliases
├── e2e/                # Playwright end-to-end tests
├── packages/
│   └── parascope-runtime/ # Standalone package for offline execution
├── docker-compose.yml  # Dev orchestration
├── docker-compose.prod.yml # Production orchestration
├── docker-compose.test.yml # Backend test orchestration
└── docker-compose.e2e.yml # E2E test orchestration

⚙️ Configuration

The application is configured via environment variables defined in a .env file. You can copy .env.example to .env to get started.

✨ Linting & Formatting

Parascope uses strict linting and formatting to maintain code quality.

Backend (Python)

We use Ruff for linting, import sorting, and formatting.

cd backend
# Check for linting issues and import sorting
uv run ruff check .
# Automatically fix linting issues and sort imports
uv run ruff check --fix .
# Format the code
uv run ruff format .

Frontend (TypeScript)

We use Biome for linting and formatting.

cd frontend
# Check for linting and formatting issues
pnpm lint
# Automatically fix issues and format the code
pnpm format

🧪 Testing

Backend unit tests are containerized and run in an isolated environment using a separate database.

To run the backend tests:

docker compose -f docker-compose.test.yml up --build --abort-on-container-exit

This will:

1. Build a test-specific backend image.
2. Start a transient PostgreSQL instance (db-test) in memory.
3. Execute all tests under backend/tests/.
4. Automatically shut down and clean up all containers upon completion.

End-to-End Tests

E2E tests use Playwright to verify the full application stack.

To run the E2E tests:

docker compose -f docker-compose.e2e.yml up --build --abort-on-container-exit --exit-code-from e2e-runner

To run a specific test file:

PLAYWRIGHT_ARGS="tests/connection-drop-menu.spec.ts" docker compose -f docker-compose.e2e.yml up --build --abort-on-container-exit --exit-code-from e2e-runner

To record videos of the test execution (saved in e2e/test-results/):

docker compose -f docker-compose.e2e.yml run -e VIDEO=on e2e-runner

This will run the tests in a completely isolated Docker project, allowing you to run them even while the main development server is active.

🧪 Database Seeding

On the first run, the database is automatically seeded with:

• Engineering Examples: Material Selection (LUT usage), Aerodynamic Drag (nested logic), and SSTO Feasibility.
• Modular Library: Reusable components for Aerospace, Fluids, Mechanics, and more, ready to be imported into new sheets.

To reset the database to these defaults, clear the sheets table or restart the backend with a fresh volume.