StockSphere

Enterprise Warehouse Management Platform. Portfolio-Grade University Project.

StockSphere is a modern Modular Monolith designed for high-performance transactional warehouse management operations, real-time inventory tracking, and predictive replenishment using AI.

---

🚀 Tech Stack Overview

• Core Backend: Node.js 22 + Fastify + TypeScript + Drizzle ORM
• Frontend: Next.js 16 + React + TypeScript + TailwindCSS + shadcn/ui + TanStack (Query, Table, Form) + Zod
• Databases & Cache: PostgreSQL (Transactional) + TimescaleDB (Time-Series Logs) + Redis (Cache & Queue)
• Object Storage: MinIO (S3-compatible Document Storage)
• AI Engine: Python FastAPI + Prophet + XGBoost + Pandas
• DevOps: Docker Compose + OrbStack + GitHub Actions

---

🛠️ Prerequisites & Setup

Ensure you have the following installed on your machine (Optimized for macOS / Apple Silicon):

• Node.js: v22.0.0 or higher
• pnpm: v10.0.0 or higher
• Docker / OrbStack
• Python: v3.10 or higher (with pip or uv package manager)

1. Installation

Clone the repository and install the workspace dependencies from the root directory:

pnpm install

2. Environment Configurations

Initialize the environment file from the template:

cp .env.example .env

Ensure database credentials inside .env align with your local configurations (the default parameters are set up out-of-the-box for the Docker Compose stack).

3. Database & Storage Provisioning

Start the backing services using Docker Compose:

pnpm db:up

This launches isolated containers for PostgreSQL, TimescaleDB, Redis, and MinIO.

---

💻 Standard Command-Line Scripts

Execute scripts from the root directory to run, build, or verify the monorepo:

Script	Command	Description
dev	pnpm dev	Starts server and web development servers concurrently
build	pnpm build	Compiles typescript-configs, schemas, and applications in build order
lint	pnpm lint	Audits lint formatting rules via ESLint Flat Configuration
typecheck	pnpm typecheck	Checks type-safety validation across all packages (no emit)
test	pnpm test	Executes all Vitest suites
test:watch	pnpm test:watch	Runs Vitest suite in watch/interactive mode
format	pnpm format	Prettifies the workspace code using Prettier rules

---

📂 Project Directory Structure

.
├── apps/
│   ├── web/                        # Next.js 16 Client App
│   ├── server/                     # Core Fastify Monolith (Backend)
│   └── ai/                         # Python FastAPI Forecasting Engine
├── packages/                       # Shared packages & configurations
│   ├── typescript-config/          # Centralized tsconfig configurations
│   └── validation-schemas/         # Common Zod validations & shared TS interfaces
├── docs/                           # Architecture, ADRs, database, and API specifications
├── docker/                         # Docker Compose definitions
└── .github/                        # CI/CD Workflows

---

🏗️ Architecture Rules & Guidelines

StockSphere is structured as a Modular Monolith. Follow these conventions strictly to maintain system clean architecture:

1. Module Boundaries: Do NOT perform direct imports between modules (e.g. apps/server/src/modules/orders must never import anything from apps/server/src/modules/inventory).
2. Module Communication:
   • For Synchronous operations, modules must execute operations through public Facades registered via Dependency Injection.
   • For Asynchronous operations, utilize the internal transactional Outbox / Event Bus.
3. Layer Separation: Clean Architecture must be followed within modules. Decouple domain models from Drizzle schemas. Keep ORM code strictly inside the infrastructure/repositories/ folder.