System-Smith

SystemSmith is a system design playground for building, exploring, and eventually simulating distributed system architectures. The project is set up like a real SaaS product: frontend and backend are independent, infrastructure is containerized, and the codebase is organized so features can grow without a rewrite.

The current version focuses on the product foundation: a working React app shell, FastAPI service, database model/migration setup, local containers, and documentation.

Repository Layout

frontend/       React, Vite, TypeScript, Tailwind, Router, Zustand, React Flow
backend/        FastAPI, SQLAlchemy, Alembic, JWT authentication
infrastructure/ Local infrastructure notes and future IaC home
docs/           Architecture and development documentation
scripts/        Helper scripts placeholder

Quick Start

1. Copy the root environment example.

   Copy-Item .env.example .env

2. Start the local stack.

   docker compose up --build

   The backend container applies database migrations before starting the API.

3. Open the app and API docs.

   • Frontend: http://localhost:5173
   • Backend API Docs: http://localhost:8000/docs
   • API Health Check: http://localhost:8000/api/v1/health
   • API Readiness Check (DB check): http://localhost:8000/api/v1/ready

Local Development

Frontend:

Set-Location frontend
corepack pnpm install
corepack pnpm dev

Backend:

Set-Location backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
uvicorn app.main:app --reload

Run database migrations after Postgres is available:

Set-Location backend
alembic upgrade head

What Is Done

Included:

• Frontend shell: Theme, routing, Zustand store, React Query, global error boundaries (catching 404s and API crashes), and responsive layouts.
• Authentication & User Profile: Login and registration, persisted frontend auth state, protected dashboard access, logout, password hashing (JWT access tokens and refresh-token rotation), and a dedicated user profile page with header menu integration.
• Project Management: User-owned workspaces with support to create, rename, delete, duplicate, list, and open projects securely. The dashboard features a responsive card grid layout for easy project management.
• Canvas Editor: A robust React Flow canvas for designing architectures isolated in its own workspace route. Features include drag-and-drop system components, node/edge selection, keyboard deletion, dirty-state tracking, unsaved-change warnings to prevent data loss, and manual save/autosave feedback.
• Backend Services: FastAPI application factory, settings, CORS, SQLAlchemy session, User/Project models, repository layers, and Alembic migrations.
• Local Infrastructure: Docker Compose with Postgres, Redis, backend, and frontend services working seamlessly together.
• Project Documentation: Comprehensive architecture and development workflow guides.

What Comes Next

Planned next work:

• Add comprehensive node configuration panels for each component type (e.g., CPU/RAM for APIs, storage/replicas for databases).
• Build a deterministic simulation engine for traffic, latency, resource usage, bottlenecks, queue depth, and cache/database load.
• Add real-time updates with WebSockets.
• Add failure simulation, autoscaling behavior, architecture templates, and later an AI provider abstraction for generated designs and reviews.

Authentication, project management, and the core canvas editor are complete and end-to-end reliable. The next product focus will be node configurations and simulation capabilities.

Architecture

See docs/architecture.md for the current architecture notes and service boundaries.