{{ project_name }} - Full-Stack Payment App

A production-ready full-stack web application built with Axum (Rust backend) and React (TypeScript frontend) for managing payments.

Features

• Modern Backend: Async REST API built with Axum framework
• React Frontend: Component-based UI with TypeScript
• Real-time Status: Live server health monitoring
• Responsive Design: Mobile-friendly interface with TailwindCSS
• CORS Enabled: Development-ready CORS configuration
• Docker Support: Containerized deployment for both services

Prerequisites

Backend

• Rust 1.70+ (Install)
• Cargo package manager

Frontend

• Node.js 18+ (Install)
• npm or yarn

Quick Start

Development Mode

1. Clone and setup:

   cd {{ project_name }}
   cp backend/.env.example backend/.env
   cp frontend/.env.example frontend/.env

2. Start Backend (Terminal 1):

   cd backend
   cargo run

   Backend runs on http://localhost:{{ backend_port }}

3. Start Frontend (Terminal 2):

   cd frontend
   npm install
   npm run dev

   Frontend runs on http://localhost:{{ frontend_port }}

4. Access the Application: Open http://localhost:{{ frontend_port }} in your browser

Docker Deployment

Build and run both services:

docker-compose up --build

• Backend: http://localhost:{{ backend_port }}
• Frontend: http://localhost:{{ frontend_port }}

API Endpoints

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "service": "x402-fullstack-api",
  "version": "0.1.0"
}

Create Payment

POST /api/payments
Content-Type: application/json

{
  "amount": 5000,
  "description": "Monthly subscription"
}

List Payments

GET /api/payments

Get Payment

GET /api/payments/:id

Project Structure

{{ project_name }}/
├── backend/
│   ├── src/
│   │   └── main.rs         # API server and routes
│   ├── Cargo.toml          # Backend dependencies
│   └── .env.example        # Environment variables template
├── frontend/
│   ├── src/
│   │   ├── main.tsx        # React entry point
│   │   ├── App.tsx         # Main application component
│   │   └── App.css         # Styling
│   ├── index.html          # HTML template
│   ├── vite.config.ts      # Vite configuration
│   ├── tsconfig.json       # TypeScript configuration
│   ├── package.json        # Frontend dependencies
│   └── .env.example        # Environment variables template
├── docker-compose.yml      # Docker services configuration
└── README.md               # This file

Development

Backend Development

cd backend

# Run development server with hot reload
cargo run

# Format code
cargo fmt

# Lint code
cargo clippy

# Run tests
cargo test

Frontend Development

cd frontend

# Install dependencies
npm install

# Start dev server with hot reload
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

Architecture

Backend (Axum)

• Framework: Axum web framework with Tokio async runtime
• API Pattern: RESTful endpoints with JSON
• State Management: Arc<Mutex<Vec>> for in-memory storage
• CORS: Permissive for development (restrict in production)
• Middleware: Tracing and CORS support

Frontend (React)

• Library: React 18 with TypeScript
• Build Tool: Vite for fast development and optimized production builds
• Styling: Plain CSS with CSS custom properties for theming
• HTTP Client: Axios for API requests
• State Management: React hooks (useState, useEffect)

Configuration

Backend Environment Variables

Create .env in backend/:

BACKEND_PORT=3000
RUST_LOG=info

Frontend Environment Variables

Create .env in frontend/:

VITE_API_BASE_URL=http://localhost:3000/api

For production, update to your production API URL.

Deployment

Production Builds

Backend:

cd backend
cargo build --release
./target/release/{{ project_name }}-backend

Frontend:

cd frontend
npm run build
# Upload `dist/` directory to static hosting

Docker Production

1. Update docker-compose.yml to use prod image tag
2. Restrict CORS in backend for production
3. Update API URLs to production domain
4. Build and push images to registry

Troubleshooting

"Connection refused" when frontend tries to reach backend

• Ensure backend is running on the correct port
• Check VITE_API_BASE_URL environment variable
• Verify CORS is enabled (it is by default)

Frontend not loading

• Clear browser cache and try again
• Check that frontend is running on the correct port ({{ frontend_port }})
• Check browser console for errors

Backend crashes on startup

• Ensure no other process is using port {{ backend_port }}
• Check RUST_LOG environment variable
• Verify Rust version is 1.70+

Docker build fails

• Ensure Docker daemon is running
• Check Docker disk space: docker system prune
• Rebuild images: docker-compose up --build

Security Notes

⚠️ This template is for development/demonstration only

Before deploying to production:

• Replace permissive CORS with specific allowed origins
• Implement authentication (JWT, OAuth, etc.)
• Add input validation and rate limiting
• Use HTTPS
• Implement proper error handling that doesn't expose internals
• Add database persistence instead of in-memory storage
• Set appropriate environment variables for production
• Use environment secrets management
• Implement logging and monitoring
• Add comprehensive error handling

Next Steps

1. Add Authentication: Integrate JWT or OAuth2
2. Database: Replace in-memory storage with PostgreSQL
3. Validation: Add comprehensive input validation
4. Testing: Write unit and integration tests
5. Monitoring: Add observability (logs, metrics, traces)
6. Documentation: Add OpenAPI/Swagger documentation
7. Styling: Enhance UI with component library

License

MIT

Support

For issues or questions:

1. Check the troubleshooting section
2. Review the code comments
3. Check Axum and React documentation
4. Open an issue on GitHub

---

Created with ❤️ by {{ author }}