Technical Documentation

System architecture, API, and deployment guides

System Architecture

Technology Stack

Frontend

• Next.js 14 (React)
• TypeScript
• Tailwind CSS
• Three.js (animations)

Backend

• FastAPI (Python)
• SQLAlchemy ORM
• Pydantic schemas
• Alembic migrations

Database

• PostgreSQL
• Redis (caching)
• File storage

Task Queue

• Celery workers
• Celery Beat scheduler
• Redis broker

Infrastructure

• Docker containers
• Docker Compose
• Nginx (optional)

Integrations

• UPS Shipping API
• QuickBooks API
• Email (SMTP)

Service Architecture

                    
┌─────────────────────────────────────────────────────────────┐
│                        Load Balancer                         │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┴─────────────────────┐
        │                                           │
        ▼                                           ▼
┌───────────────┐                         ┌───────────────┐
│   Frontend    │                         │    Backend    │
│   (Next.js)   │ ◄───── REST API ──────► │   (FastAPI)   │
│   Port: 3002  │                         │   Port: 8000  │
└───────────────┘                         └───────┬───────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────────────┐
                    │                             │                             │
                    ▼                             ▼                             ▼
            ┌───────────────┐             ┌───────────────┐             ┌───────────────┐
            │  PostgreSQL   │             │     Redis     │             │    Celery     │
            │   Database    │             │ Cache/Broker  │             │   Workers     │
            │   Port: 5432  │             │   Port: 6379  │             │               │
            └───────────────┘             └───────────────┘             └───────────────┘
                    
                

API Reference

Base URL

http://localhost:8000/api/v1

Authentication

All API requests (except login/register) require a Bearer token in the Authorization header.

Authorization: Bearer <your_access_token>

Key Endpoints

Authentication

POST /auth/login - User login

POST /auth/register - User registration

GET /users/me - Get current user

Kit Orders

GET /kit-orders - List kit orders

POST /kit-orders - Create kit order

GET /kit-orders/{id} - Get kit order details

PUT /kit-orders/{id}/ship - Mark as shipped

PUT /kit-orders/{id}/deliver - Mark as delivered

Samples

GET /samples - List samples

POST /samples/upload - Upload plate map

GET /plate-mappings - List plate mappings

Orders & Workflow

GET /orders - List orders

GET /orders/{id}/progress - Get order progress

PUT /orders/{id}/workflow - Update workflow step

Database Schema

Core Models

User

id: Integer (PK)
email: String (unique)
full_name: String
role: Enum (customer, lab_technician, admin)
company_name: String
shipping_address: JSON
lab_address: JSON

KitOrder

id: Integer (PK)
order_number: String (unique)
customer_id: Integer (FK → User)
status: String
number_of_plates: Integer
tracking_number: String
shipped_at: DateTime

Plate

id: Integer (PK)
barcode: String (unique)
kit_order_id: Integer (FK)
well_count: Integer (96)
status: String

Sample

id: Integer (PK)
name: String
species: String
sample_type: Enum
well_position: String
plate_id: Integer (FK)
status: String

Integration Guides

UPS Shipping Integration

The UPS integration uses OAuth 2.0 for authentication and provides shipping label generation and tracking.

Required Environment Variables

                    
UPS_CLIENT_ID=your_client_id
UPS_CLIENT_SECRET=your_client_secret
UPS_ACCOUNT_NUMBER=your_account_number

Features

• Automatic shipping label generation
• Tracking number creation
• Delivery status updates (via Celery Beat)
• Return label generation

QuickBooks Integration

QuickBooks integration uses OAuth 2.0 for customer and invoice management.

Required Environment Variables

                    
QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_REALM_ID=your_realm_id
QUICKBOOKS_REDIRECT_URI=your_redirect_uri

Features

• Customer sync
• Invoice creation
• Payment tracking
• Automatic token refresh

Deployment Guide

Docker Deployment

Start All Services

docker-compose up -d

Run Database Migrations

docker-compose exec backend alembic upgrade head

View Logs

                    
docker-compose logs backend --tail=50
docker-compose logs frontend --tail=50
docker-compose logs celery --tail=50

Restart Services

docker-compose restart backend frontend

Environment Setup

Required Environment Variables

Security Warning

Never commit actual credentials to version control. Use environment variables or secure vaults for sensitive data.

Example .env Structure

                    
# Database
DATABASE_URL=postgresql://user:password@db:5432/lims_db

# Redis
REDIS_URL=redis://redis:6379/0

# Security
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret

# Email
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email
SMTP_PASSWORD=your-password

# UPS Integration (configure with your credentials)
UPS_CLIENT_ID=xxx
UPS_CLIENT_SECRET=xxx
UPS_ACCOUNT_NUMBER=xxx

# QuickBooks (configure with your credentials)
QUICKBOOKS_CLIENT_ID=xxx
QUICKBOOKS_CLIENT_SECRET=xxx
                    
                