Liquidity/
│
├── 🎨 frontend/ # Next.js Frontend Application
│ ├── app/ # Next.js App Router
│ │ ├── page.tsx # Main landing page
│ │ ├── layout.tsx # Root layout
│ │ └── globals.css # Global styles
│ ├── lib/ # Utilities & API Client
│ │ └── api.ts # TypeScript API client
│ ├── public/ # Static assets
│ ├── .env.local # Environment variables
│ ├── package.json # Node.js dependencies
│ └── tsconfig.json # TypeScript config
│
├── 🔧 backend/ # FastAPI Backend Application
│ ├── app/ # Application code
│ │ ├── main.py # FastAPI app & routes
│ │ └── __init__.py # Package initialization
│ ├── venv/ # Python virtual environment (created by setup)
│ ├── requirements.txt # Python dependencies
│ ├── .env.example # Environment template
│ ├── setup.sh # Backend setup script
│ └── start-backend.sh # Backend start script
│
├── 📁 src/ # Your existing code
│ └── solver/ # Solver module
│ └── solver.py # Liquidity solver logic
│
├── 📄 Documentation
│ ├── README.md # Comprehensive documentation
│ ├── QUICKSTART.md # Quick start guide
│ └── ARCHITECTURE.md # This file
│
├── 🚀 Utility Scripts
│ ├── start-all.sh # Start both servers
│ └── check-system.sh # System prerequisites check
│
└── ⚙️ Configuration
└── .gitignore # Git ignore rules
┌─────────────────────────────────────────────────────────────┐
│ User Browser │
│ http://localhost:3000 │
└─────────────────────┬───────────────────────────────────────┘
│
│ HTTP Requests
▼
┌─────────────────────────────────────────────────────────────┐
│ Next.js Frontend │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ React Components (page.tsx) │ │
│ │ - UI rendering │ │
│ │ - User interactions │ │
│ │ - State management │ │
│ └────────────────┬───────────────────────────────────────┘ │
│ │ │
│ │ Uses │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ API Client (lib/api.ts) │ │
│ │ - Type-safe API calls │ │
│ │ - Error handling │ │
│ │ - Request/Response formatting │ │
│ └────────────────┬───────────────────────────────────────┘ │
└───────────────────┼──────────────────────────────────────────┘
│
│ fetch() / HTTP
│ http://localhost:8000/api/*
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Backend │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ CORS Middleware │ │
│ │ - Allow Next.js origin │ │
│ └────────────────┬───────────────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ API Routes (main.py) │ │
│ │ - /health Health check │ │
│ │ - /api/hello Sample endpoint │ │
│ │ - /api/items Get items list │ │
│ │ - /api/process Process item │ │
│ └────────────────┬───────────────────────────────────────┘ │
│ │ │
│ │ Can use │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Your Business Logic │ │
│ │ - src/solver modules │ │
│ │ - Database operations │ │
│ │ - External services │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
| Service | URL | Purpose |
|---|---|---|
| Frontend | http://localhost:3000 |
User-facing web interface |
| Backend API | http://localhost:8000 |
REST API endpoints |
| API Docs (Swagger) | http://localhost:8000/docs |
Interactive API documentation |
| API Docs (ReDoc) | http://localhost:8000/redoc |
Alternative API documentation |
The backend is configured to accept requests from the frontend:
- Allowed Origins:
http://localhost:3000 - Allowed Methods: All (
GET,POST,PUT,DELETE, etc.) - Allowed Headers: All
- Credentials: Enabled
NEXT_PUBLIC_API_URL=http://localhost:8000API_HOST=0.0.0.0
API_PORT=8000
DEBUG=True
CORS_ORIGINS=http://localhost:3000Next.js 15 (React 19)
├── TypeScript # Type safety
├── Tailwind CSS # Utility-first styling
├── App Router # File-based routing
└── Server Components # Performance optimization
FastAPI
├── Uvicorn # ASGI server
├── Pydantic # Data validation
├── Python 3.8+ # Runtime
└── Automatic OpenAPI # API documentation
- next: React framework with SSR/SSG
- react & react-dom: UI library
- typescript: Type checking
- tailwindcss: CSS framework
- eslint: Code linting
- fastapi: Web framework
- uvicorn: ASGI server
- pydantic: Data validation
- python-dotenv: Environment variables
# Check prerequisites
./check-system.sh
# Setup backend
cd backend && ./setup.sh && cd ..
# Setup frontend (if needed)
cd frontend && npm install && cd ..# Option 1: Start both together
./start-all.sh
# Option 2: Start separately
# Terminal 1
cd backend && ./start-backend.sh
# Terminal 2
cd frontend && npm run devAdding a new API endpoint:
- Define route in
backend/app/main.py - Add method to
frontend/lib/api.ts - Use in React components
Adding a new page:
- Create
frontend/app/your-page/page.tsx - Access at
http://localhost:3000/your-page
To integrate your existing src/solver code:
# backend/app/main.py
import sys
sys.path.append('../src')
from solver.solver import YourSolverClass
@app.post("/api/solve")
async def solve_problem(data: ProblemData):
solver = YourSolverClass()
result = solver.solve(data)
return {"solution": result}- Configure production environment variables
- Set up database (PostgreSQL, MongoDB, etc.)
- Add authentication/authorization
- Implement rate limiting
- Add logging and monitoring
- Configure HTTPS/SSL
- Set up CI/CD pipeline
- Configure CORS for production domains
- Optimize build for production
- Set up error tracking (Sentry, etc.)
Frontend (Next.js)
- Vercel (recommended)
- Netlify
- AWS Amplify
- Self-hosted with PM2
Backend (FastAPI)
- Railway
- Render
- Heroku
- AWS EC2/ECS
- DigitalOcean
- Self-hosted with Nginx + Gunicorn
When adding features:
- Follow the existing code structure
- Add types to TypeScript code
- Use Pydantic models for API schemas
- Update documentation
- Test both frontend and backend