nexus-4/README.md

Nexus 4

A Rust-based business management API experiment featuring Actix-web, SeaORM, and async-graphql. This project was an exploration into building a high-performance backend with Rust but was ultimately abandoned in favor of returning to more familiar frameworks (Django) for Nexus 5.

Project Status: Abandoned

While the API itself demonstrated significantly better performance characteristics than the Python-based predecessors, the project was discontinued due to:

• Learning curve: Rust's ownership model and borrow checker, while excellent for safety, required significant time investment
• Ecosystem maturity: The Django/Python ecosystem offered more battle-tested solutions for rapid business application development
• Team familiarity: Returning to Django allowed faster iteration and easier maintenance

Despite being abandoned, this codebase serves as a reference implementation for building GraphQL APIs in Rust.

What Was Achieved

• Full GraphQL API with queries and mutations for all entities
• JWT authentication with bcrypt password hashing
• SeaORM entities with PostgreSQL
• Database migrations
• SvelteKit frontend with Houdini GraphQL client
• CORS configuration for frontend integration

Performance Comparison

Metric	Nexus 3 (Django/Graphene)	Nexus 4 (Rust/async-graphql)
Memory usage	~150MB	~15MB
Cold start	~2-3s	~50ms
Simple query latency	~20-50ms	~2-5ms
Concurrent connections	Hundreds	Thousands

Note: These are approximate benchmarks from development testing, not production measurements.

Improvements Over Previous Versions

Over Nexus 1-2 (Django REST)

• GraphQL instead of REST
• Compiled binary instead of interpreted Python
• Zero-cost abstractions and memory safety
• Native async/await without GIL limitations

Over Nexus 3 (Django/Graphene)

• ~10x lower memory footprint
• ~10x faster query response times
• True async I/O without Python's GIL
• Type safety at compile time
• Single binary deployment

Tech Stack

Backend

• Rust (2024 edition)
• Actix-web 4.x - High-performance web framework
• SeaORM 1.x - Async ORM with compile-time checked queries
• async-graphql 7.x - GraphQL server library
• jsonwebtoken - JWT authentication
• bcrypt - Password hashing
• PostgreSQL - Database

Frontend

• SvelteKit - Frontend framework
• Houdini - GraphQL client with generated types
• TypeScript

Project Structure

nexus-4/
├── src/
│   ├── main.rs           # Application entry point
│   ├── db.rs             # Database connection
│   ├── auth/             # JWT authentication
│   │   ├── mod.rs        # JWT middleware and utilities
│   │   ├── error.rs      # Auth error types
│   │   └── handlers.rs   # Login, register, token renewal
│   ├── entities/         # SeaORM entities
│   │   ├── mod.rs
│   │   ├── prelude.rs
│   │   ├── customer.rs
│   │   ├── account.rs
│   │   ├── service.rs
│   │   ├── project.rs
│   │   ├── schedule.rs
│   │   ├── revenue.rs
│   │   ├── labor.rs
│   │   ├── invoice.rs
│   │   ├── report.rs
│   │   ├── user.rs
│   │   └── profile.rs
│   └── graphql/          # GraphQL resolvers
│       ├── mod.rs        # Schema definition
│       ├── customer.rs
│       ├── account.rs
│       ├── service.rs
│       ├── project.rs
│       ├── schedule.rs
│       ├── revenue.rs
│       ├── labor.rs
│       ├── invoice.rs
│       ├── report.rs
│       ├── user.rs
│       └── profile.rs
├── migration/            # SeaORM migrations
│   └── src/
│       ├── lib.rs
│       └── m20220101_*.rs
├── frontend/             # SvelteKit + Houdini frontend
│   ├── src/
│   ├── .houdini/         # Generated GraphQL artifacts
│   └── schema.graphql    # GraphQL schema
├── Cargo.toml
└── Cargo.lock

Quick Start

Prerequisites

• Rust (latest stable)
• PostgreSQL 15+
• Node.js 18+ (for frontend)

Backend Setup

# Clone the repository
git clone <repository-url>
cd nexus-4

# Create .env file
cat > .env << EOF
DATABASE_URL=postgres://user:password@localhost/nexus4
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRATION=3600
EOF

# Run migrations
cd migration
cargo run

# Start the server
cd ..
cargo run

The server will start at:

• GraphQL endpoint: http://127.0.0.1:8080/graphql
• GraphQL playground: http://127.0.0.1:8080/playground
• Auth endpoint: http://127.0.0.1:8080/token

Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

API Usage

Authentication

Login:

curl -X POST http://localhost:8080/token \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

Create User:

curl -X POST http://localhost:8080/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "securepassword",
    "is_active": true,
    "first_name": "John",
    "last_name": "Doe",
    "primary_phone": "555-123-4567",
    "role": "user"
  }'

GraphQL Queries

Get all customers:

query {
  customers {
    id
    name
    accounts {
      id
      name
    }
  }
}

Create a service:

mutation {
  createService(input: {
    accountId: "uuid-here"
    status: "scheduled"
    scheduledDate: "2024-01-15"
  }) {
    id
    status
  }
}

Configuration

Environment Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
JWT_SECRET	Secret for signing JWTs	default_secret_change_me
JWT_EXPIRATION	Token expiration in seconds	3600

Why Rust Was Considered

1. Performance: Rust's zero-cost abstractions provide C-like performance
2. Memory Safety: No null pointer exceptions or data races
3. Concurrency: Fearless concurrency with async/await
4. Type System: Catch errors at compile time
5. Single Binary: Easy deployment without runtime dependencies

Why It Was Abandoned

1. Development Speed: Django's ORM and admin interface provide faster iteration
2. Ecosystem: Python has more libraries for business logic (PDF generation, email, etc.)
3. Hiring: Finding Django developers is easier than Rust developers
4. Maintenance: Team was more comfortable debugging Python code

Lessons Learned

• Rust is excellent for performance-critical services
• For CRUD-heavy business apps, developer productivity often matters more than raw performance
• Consider Rust for specific microservices where performance is critical
• The async-graphql and SeaORM ecosystem is mature and pleasant to use

License

MIT License - See LICENSE file for details.