CamMana-Compact 🚛

A modern, high-performance specialized system for managing vehicle entries with OCR license plate recognition. Upgraded to a robust microservices architecture using Next.js, FastAPI, and PocketBase, all orchestrated via Docker.

🚀 Architecture

The system utilizes Docker with Profiles to seamlessly switch between Development and Production workflows.

Component	Technology	Role
Frontend	Next.js 16 + Chakra UI v3	Modern UI with Dark Mode.
Backend	FastAPI + uv	High-performance Python API.
State Management	Zustand + React Query	Advanced sync & state patterns.
Database	PocketBase	Real-time Database & Auth.
Statistics	Recharts + @chakra-ui/charts	Visual analytics dashboard.
Backup	Alpine + Cron	Automated production backups.

---

🛠 Environments & Ports

Environment	Host Port	Database Host	Purpose
Development	3000 / 8000 / 8090	localhost	Local dev with .env.dev
Production	3001 / 8001 / 8091	pocketbase-prod	Full Docker with .env.prod

---

⚡ Quick Start

1. Development (Terminal + Docker Tunnel)

Run the apps directly on your terminal for the fastest development cycle, but use Docker for the Cloudflare Tunnel.

Step 1: Configure Environment

# Set development variables
copy .env.dev .env

Step 2: Start Backend (Terminal)

cd backend
uv sync
uv run main.py        # Runs on port 8000

Step 3: Start Frontend (Terminal)

cd frontend
npm install
npm run dev           # Runs on port 3000

2. Production (Full Docker)

Run the entire stack in isolated containers.

✅ Pre-Deployment Checklist

1. Frontend Lint: cd frontend && npm run lint (Must pass)
2. Frontend Build: cd frontend && npm run build (Ensures zero compilation errors)
3. Backend Sync: cd backend && uv sync (Ensures dependencies are locked)
4. Env Config: Production variables are automatically loaded from .env.prod via Docker Compose profiles.

Deployment Commands

# Stop dev containers/tunnels
docker compose down --remove-orphans

# Start Production Stack (Uses .env.prod automatically)
docker compose --profile prod up -d --build

Access App at http://localhost:3001 (or your production domain) (Auto-backups run every 2 hours)

🛑 Stopping Production

To stop only the production containers while keeping your Development environment running:

docker compose --profile prod down

• Why this is safe: Because we use Docker Profiles, down --profile prod will only target production services. Your pocketbase-dev container and your uv run / npm dev processes will remain completely untouched.
• Data Safety: Your production data is stored in the pb_data volume and is NOT deleted by the down command.

---

📊 New Features

• Statistics Dashboard: Real-time visual tracking of volume distribution, vehicle counts, and entry patterns.
• Advanced State Management: Sub-second UI reactivity using Zustand and server-state synchronization with TanStack Query.
• Unified UI: Perfectly consistent design system built on Chakra UI v3 with full Dark Mode support.

---

📂 Project Structure

• backend/: FastAPI application (Python).
• frontend/: Next.js application (React).
• docs/:
  • technical/: Architecture & Docker guides.
  • planning/: Future roadmap.
  • archive/: Phase 1 docs.
  • USER_GUIDE.md: User manual.
• docker-compose.yml: Main orchestration file.
• .env: Global configuration (Ports, Credentials).

🔧 Configuration

• Development: Copy .env.dev to .env for local terminal runs.
• Production: Docker Compose automatically uses .env.prod via env_file directives in docker-compose.yml.
• Secrets: Both .env.dev and .env.prod should be kept secure. Individual local overrides can be made in a root .env (git-ignored).

🏷️ Versioning

The project uses APP_VERSION in your .env files to tag Docker images.

1. To increment: Change APP_VERSION=1.0.0 to APP_VERSION=1.0.1 in .env.prod.
2. To build: Run docker compose --profile prod up -d --build.
3. To rollback: Simply change the version back in .env.prod and run the command again. Docker will use the previously built image for that version instantly.

---

Created with ❤️ for Advanced Vehicle Management.