Rext Demo Project

This is a simple demo project that showcases all the features Rext will incorporate. This project was not created by Rext, but it is a good example of what Rext will be able to do.

Getting Started

• In example_rext_project run cargo run.
• In example_rext_project/frontend run npm i && npm run dev

This spins up a Rust server listening on port 3000 and a Vite server running on port 5173.

The Rust server has a CORS bypass that allows these two ports to communicate via HTTP on localhost. In a real Rext app, we'll use self-signed certificates and domains on local host so we can use HTTPS and avoid CORS issues.

Features

• Frontend - Written in Vue with Vue Router
• Database - a sqlite database for getting up and running quickly. Support for MySQL, Postgresql, and sqlite will be goals.
• ORM - an object relational model for accessing the database via sea-orm
• Web Server - powered by axum
• Routing - powered by the web server
• Authentication - simple yet secure authentication with argon2 and jsonwebtoken.
• SPA Navigation - reactive authentication state with seamless single-page app experience
• OpenAPI Generation - Generates an OpenAPI document and serves SwaggerUI, Redoc, and Scalar pages
• Middleware - A simple middleware implementation for authentication
• API Client - A Type-safe API client generated by Hey API for types and API requests
• Task Scheduler - A task scheduler built on top of apalis
• Job Queue - A job queue built on top of apalis
• Layered Architecture - A clean separation of concerns between frontend and backend, with clear boundaries between each layer.
• Admin Panel - A dashboard where you can view request logs, manage users, manager user sessions, manage user roles, view database tables and records, monitor system health, and view requests and logs in real time view a real time web socket connection.
• Logging - Middleware logs all HTTP requests in an audit table.
• Users and Roles - Manage users and their permissions via a simple and extensible roles system.
• System Metrics - View system health, uptime, performance, errors, activity, and system resources.
• User Sessions - View all active user sessions and invalidate sessions remotely.
• Email Service - Send emails via SMTP.
• WebSocket Metrics - Broadcast metrics to all connected clients.
• Email Verification - Send verification emails to new users.

How to use

• Navigate to http://localhost:5173/ in your browser to view the Demo Vue app.
• Visit /register to create an account.
  • Email needs to be in email format, but it doesn't need to be real. Password is hashed with argon2 on the backend.
  • If you get network errors, be sure you're on localhost, not 127.0.0.1, same thing in concept but the CORS bypass is only set up for localhost.
• After registering, you can login at /login.
  • This passes you a token that is stored in your browser.
• This should route you to /profile.
  • This is a protected route, you can only access it when logged in. Should redirect to /login if logged out.
• Logout using the "Logout" button in the navigation bar, which removes the token from your browser and updates the UI in real-time.
• Visit the API docs at localhost:3000/scalar
• Login to the admin panel at /admin/login.
  • From here you can manage users, view logs, view database records, and view system health metrics.

Admin Access

Default Admin User:

• Email: admin@localhost.com
• Password: admin123
• Note: This user is automatically created when the application starts for the first time.

Admin API Endpoints:

• Admin login: POST /api/v1/admin/login
• View API documentation: http://localhost:3000/scalar (look for "Admin" tag)

Admin Panel Access:

• Frontend URL: http://localhost:5173/admin/login

🚀 Deployment

The project includes comprehensive deployment options for both development and production environments.

Quick Deployment Options

Docker (Recommended)

# Quick production deployment
cp example.env .env  # Configure your environment
docker-compose up -d

Bare Metal

# Automated setup and build
./scripts/dev-setup.sh      # Development setup
./scripts/build-production.sh # Production build

Deployment Methods

• 🐳 Docker Deployment: Single container with multi-stage build
• 🖥️ Bare Metal Deployment: Native binary with frontend assets
• 📦 Build Automation: Automated frontend building via build.rs
• 🛠️ Development Scripts: Convenient setup and development workflows

See DEPLOYMENT.md for comprehensive deployment instructions.

Production Features

• ✅ Multi-stage Docker build optimized for production
• ✅ Automated frontend asset building and bundling
• ✅ Single binary deployment with embedded static serving
• ✅ Environment-based configuration
• ✅ Database migrations included
• ✅ Health checks and monitoring ready
• ✅ Security-hardened defaults
• ✅ Email service with SMTP and AWS SES support
• ✅ WebSocket metrics broadcasting
• ✅ Admin panel with real-time metrics and logs
• ✅ User management and authentication
• ✅ Database migrations
• ✅ Health checks and monitoring

Architecture

This project takes a layered approach to architecture with clear separation of concerns between frontend, backend, and database layers.

Project Structure

example_rext_project/
├── backend/                   # Rust backend application
│   ├── main.rs                # Application entry point and server setup
│   ├── bridge/                # Web API layer (HTTP handlers, routes, middleware)
│   │   ├── mod.rs
│   │   ├── handlers/          # HTTP request handlers
│   │   │   ├── mod.rs
│   │   │   └── auth.rs        # Authentication handlers
│   │   ├── routes/            # API route definitions
│   │   │   ├── mod.rs
│   │   │   └── auth.rs        # Authentication routes
│   │   ├── middleware/        # HTTP middleware
│   │   │   ├── mod.rs
│   │   │   └── auth.rs        # Authentication middleware
│   │   └── types/             # API-specific types
│   │       ├── mod.rs
│   │       └── auth.rs        # Authentication types
│   ├── control/               # Business logic layer
│   │   └── services/          # Service implementations
│   ├── domain/                # Domain models and business rules
│   ├── entity/                # Database entity layer (Sea-ORM)
│   │   ├── mod.rs
│   │   └── models/            # Database entity models
│   │       ├── mod.rs
│   │       ├── prelude.rs     # Common entity imports
│   │       └── users.rs       # User entity model
│   └── infrastructure/        # Infrastructure concerns
│       ├── mod.rs
│       ├── app_error.rs       # Application error types
│       └── jwt_claims.rs      # JWT token claims
├── frontend/                  # Vue.js frontend application
│   ├── src/
│   │   ├── main.ts            # Frontend entry point
│   │   ├── App.vue            # Root Vue component
│   │   ├── appearance/        # Presentation layer
│   │   │   ├── components/    # Reusable Vue components
│   │   │   └── views/         # Page views
│   │   │       ├── HomeView.vue      # Landing page
│   │   │       ├── LoginView.vue     # User login form
│   │   │       ├── RegisterView.vue  # User registration form
│   │   │       └── ProfileView.vue   # User profile page
│   │   └── bridge/            # API client layer
│   │       ├── client/        # Generated API client
│   │       │   ├── client/    # Core client implementation
│   │       │   ├── core/      # Client utilities and types
│   │       │   ├── client.gen.ts     # Generated client code
│   │       │   ├── sdk.gen.ts # Generated SDK
│   │       │   └── types.gen.ts      # Generated types
│   │       └── router/        # Vue Router configuration
│   ├── e2e/                   # End-to-end tests (Playwright)
│   │   ├── tsconfig.json      # E2E TypeScript config
│   │   └── vue.spec.ts        # E2E test specifications
│   ├── config/                # Build and tooling configuration
│   │   └── unified.config.ts  # Unified configuration
│   ├── package.json           # Frontend dependencies
│   ├── vite.config.ts         # Vite build configuration
│   ├── tsconfig.json          # TypeScript configuration
│   └── eslint.config.ts       # ESLint configuration
├── migration/                 # Database migration system (Sea-ORM)
│   ├── src/
│   │   ├── lib.rs             # Migration registry and setup
│   │   ├── main.rs            # Migration runner
│   │   └── m20250720_000001_create_users.rs  # Users table migration
│   ├── Cargo.toml             # Migration dependencies
│   └── README.md              # Migration documentation
├── Cargo.toml                 # Rust workspace configuration
├── rext.toml                  # Rext framework configuration
├── example.env                # Environment variables template
└── README.md                  # Project documentation

Architecture Layers

Backend (Rust)

• Bridge Layer: HTTP API endpoints, middleware, and request/response handling
• Control Layer: Business logic and service orchestration
• Domain Layer: Core business models and rules
• Entity Layer: Database models and ORM integration (Sea-ORM)
• Infrastructure Layer: Cross-cutting concerns (errors, JWT, etc.)

Frontend (Vue.js)

• Appearance Layer: UI components and page views
• Bridge Layer: API client and routing
• Client Layer: Generated type-safe API client

Database

• Migration System: Version-controlled database schema changes
• Entity Models: Type-safe database access with Sea-ORM

Key Design Principles

1. Separation of Concerns: Clear boundaries between presentation, business logic, and data layers
2. Type Safety: Full TypeScript on frontend, strong typing in Rust backend
3. API-First: OpenAPI specification with generated clients
4. Layered Architecture: Clean separation between HTTP, business logic, and data access
5. Generated Code: Type-safe API clients and database entities generated from specifications