Warehouse Neuron 🧠

A neural upgrade for traditional warehouse management systems

Modern inventory tracking with barcode scanning, real-time updates, and intelligent workflows.

🎯 Project Vision

Transform inventory management from a chore into an intelligent, responsive system:

• 📱 Mobile-First: Scan barcodes anywhere in the warehouse
• ⚡ Real-Time: Instant stock updates via Redis streams
• 🔍 Complete Audit Trail: Every movement tracked and traceable
• 🌐 Multi-Platform: Web, mobile, and desktop from one codebase
• 🚀 Cloud-Ready: Designed for scale and reliability

Current Status: Phase A - Backend + Web Dashboard Complete!

---

🌐 Access Points

• Web Dashboard: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs (Swagger): http://localhost:8000/docs
• Database (DBeaver): localhost:5434

---

📋 Phase A Progress

✅ Completed

• Nix flake development environment with automatic venv
• Docker Compose multi-service setup (Postgres, Redis, FastAPI)
• SQLAlchemy schema with 5 core tables
• FastAPI backend with stock intake endpoint
• Redis event streaming for real-time updates
• Database connection pooling
• Code formatting (Black + isort)
• API documentation (Swagger UI)
• Comprehensive testing guides
• Flutter web dashboard with stock intake interface
• CORS middleware for web access

🚧 In Progress

• Database migrations (Alembic)
• Flutter mobile app (Android + iOS)
• Tauri desktop wrapper
• Authentication system
• Unit and integration tests
• Real-time statistics dashboard

📚 Documentation

• API Guide - Complete API reference with Postman/DBeaver guides
• Database Setup - Schema, migrations, and maintenance
• Web Dashboard README - Flutter web app guide
• APP.md - Full project vision and roadmap

---

🚀 Quick Start

Prerequisites

• Nix with flakes enabled
• direnv (optional but recommended)
• Docker or Podman

1. Setup Environment

# Clone the repository
git clone <repository-url>
cd warehouse-neuron

# Allow direnv (automatic environment)
direnv allow

# Or manually activate Nix environment
nix develop

The Nix environment provides:

• Python 3.13.8 with venv
• Black & isort formatters
• All backend dependencies

2. Start Services

# Start all services (Postgres, Redis, Backend)
docker compose up -d

# View logs
docker compose logs -f backend

3. Initialize Database

# Run initial migration
docker exec -i warehouse-neuron_postgres_1 psql -U wn_user -d warehouse_neuron < services/migrations/0001_init.sql

# Verify tables created
docker exec -it warehouse-neuron_postgres_1 psql -U wn_user -d warehouse_neuron -c '\dt'

4. Test API

Open http://localhost:8000/docs in your browser to access the interactive API documentation.

Quick test:

curl http://localhost:8000/health
# Expected: {"status":"healthy"}

---

🏗️ Architecture

Tech Stack

Backend:

• FastAPI 0.121.0 - Modern async web framework
• PostgreSQL 15 - Primary data store
• Redis 7 - Event streaming and caching
• SQLAlchemy 2.0 - Async ORM
• Pydantic 2.12 - Data validation

Frontend (Coming):

• Flutter - Cross-platform UI (mobile + web)
• Tauri - Desktop wrapper (Windows, macOS, Linux)

DevOps:

• Nix Flakes - Reproducible environments
• Docker Compose - Local development
• GitHub Actions - CI/CD (future)

Database Schema

locations          → Warehouse zones/bins
skus               → Product catalog
sku_barcodes       → Barcode mappings (many-to-one)
stock_ledger       → Current inventory levels
stock_movements    → Complete transaction history

See DATABASE_SETUP.md for detailed schema documentation.

---

📁 Project Structure

warehouse-neuron/
├── flake.nix                   # Nix development environment
├── .envrc                      # direnv auto-activation
├── docker-compose.yml          # Multi-service orchestration
├── README.md                   # This file
├── APP.md                      # Project vision & roadmap
├── docs/
│   ├── API_GUIDE.md           # Complete API documentation
│   └── DATABASE_SETUP.md      # Database guide
├── apps/                       # Frontend applications (future)
└── services/
    ├── backend/                # FastAPI backend
    │   ├── Dockerfile
    │   ├── requirements.txt
    │   └── app/
    │       ├── main.py         # Application entry point
    │       ├── config.py       # Settings management
    │       ├── database.py     # DB connection pool
    │       ├── models.py       # SQLAlchemy models
    │       ├── schema.py       # Pydantic schemas
    │       ├── crud.py         # Database operations
    │       └── routes/
    │           └── stock.py    # Stock management API
    └── migrations/
        └── 0001_init.sql       # Initial schema

---

🔧 Development Workflow

Code Formatting

# Format all Python files
black .
isort .

# Check without changes
black --check .
isort --check-only .

Docker Operations

# Start services
docker compose up -d

# Rebuild after code changes
docker compose up -d --build --no-cache

# View logs
docker compose logs -f backend

# Stop services
docker compose down

# Reset everything
docker compose down -v  # Removes volumes too

Database Access

# Connect via psql
psql -h localhost -p 5434 -U wn_user -d warehouse_neuron

# Or via Docker
docker exec -it warehouse-neuron_postgres_1 psql -U wn_user -d warehouse_neuron

# Run query
docker exec -it warehouse-neuron_postgres_1 psql -U wn_user -d warehouse_neuron -c 'SELECT * FROM skus;'

---

🌐 Service Endpoints

Backend API

• Base URL: http://localhost:8000
• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Database (PostgreSQL)

• Host: localhost
• Port: 5434 (external), 5432 (internal)
• Database: warehouse_neuron
• User: wn_user
• Password: wn_pass

Redis

• Host: localhost
• Port: 6379

---

📚 API Reference

Key Endpoints

Health Check

GET /health

Stock Intake (Main Feature)

POST /api/v1/stock/intake
Content-Type: application/json

{
  "barcode": "123456789012",
  "qty": 10,
  "location_code": "WH-A-01",
  "movement_type": "IN",
  "auto_create_sku": true,
  "created_by": "user@example.com"
}

Interactive Documentation

• Full API reference: http://localhost:8000/docs
• Complete testing guide: docs/API_GUIDE.md

---

🧪 Testing

API Testing with Postman

See API_GUIDE.md for:

• Postman collection setup
• Example requests
• Complete testing scenarios

Database Testing with DBeaver

See DATABASE_SETUP.md for:

• Connection setup
• Sample queries
• Performance monitoring

Manual Testing

# Test health endpoint
curl http://localhost:8000/health

# Test stock intake
curl -X POST http://localhost:8000/api/v1/stock/intake \
  -H "Content-Type: application/json" \
  -d '{"barcode":"TEST-001","qty":10,"auto_create_sku":true}'

---

📦 Environment Variables

Backend service configuration (set in docker-compose.yml):

DATABASE_URL=postgresql+asyncpg://wn_user:wn_pass@postgres:5432/warehouse_neuron
REDIS_URL=redis://redis:6379
APP_ENV=development

---

🛠️ Troubleshooting

Services won't start

# Check container status
docker ps -a

# View logs
docker compose logs backend
docker compose logs postgres

# Restart services
docker compose restart

Port conflicts

# Check what's using port 5434
netstat -tuln | grep 5434

# Or use different port in docker-compose.yml

Database connection failed

# Test from host
psql -h localhost -p 5434 -U wn_user -d warehouse_neuron

# Test from container
docker exec warehouse-neuron_postgres_1 pg_isready -U wn_user

See troubleshooting sections in:

• API_GUIDE.md
• DATABASE_SETUP.md

---

🗺️ Roadmap

Phase A - Foundations (Current)

Backend scaffold, schema, basic scanning

Phase B - Reliability

Error handling, offline queue, retry logic

Phase C - Intelligence

AI-powered predictions, anomaly detection

Phase D - Optimization

Multi-warehouse, advanced analytics

Phase E - Polish

UI/UX refinement, performance tuning

See APP.md for complete roadmap details.

---

🤝 Contributing

1. Follow existing code style (Black + isort)
2. Run formatters before committing
3. Test changes locally with Docker Compose
4. Update documentation for new features
5. Write tests for new functionality

---

📄 License

[License TBD]

---

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• API Docs: http://localhost:8000/docs

---

Built with ❤️ for modern warehouse operations