Kobizo E-commerce

Modern e-commerce platform with Next.js frontend, Express API gateway, and Directus headless CMS.

Architecture

graph TB
    A[Next.js 14<br/>Frontend<br/>Port 3000]
    B[Express API<br/>BFF/Gateway<br/>Port 4000]
    C[Directus CMS<br/>Headless CMS<br/>Port 8055]
    D[(PostgreSQL<br/>Database)]

    A -->|HTTP/Cookies<br/>SSR, SSG+ISR| B
    B -->|REST API<br/>Auth, Validation| C
    C -->|SQL| D

    style A fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
    style B fill:#68a063,stroke:#333,stroke-width:2px,color:#fff
    style C fill:#6644ff,stroke:#333,stroke-width:2px,color:#fff
    style D fill:#336791,stroke:#333,stroke-width:2px,color:#fff

Loading

Features

Authentication

• JWT tokens stored in HTTP-only cookies
• Signup and login through API gateway
• Protected routes

Products

• Server-side rendered catalog
• Filters: search, price range, pagination
• Stock validation before checkout
• Cart requires login

Blog

• Static generation with ISR (revalidates every 60s)
• Markdown content support

Checkout

• Stock validation per item
• Payment form validation
• Test mode with demo card

Security

• Helmet, CORS, rate limiting
• Input sanitization
• Request size limits

Stack

• Next.js 14, TypeScript, Tailwind, Zustand
• Express, Zod, JWT
• Directus 11, PostgreSQL
• Jest, React Testing Library
• pnpm workspaces, ESLint, Prettier

Prerequisites

• Node.js 18+
• pnpm 8+
• Docker & Docker Compose

Quick Start

Option 1: With Docker (Easiest)

docker compose up -d

That's it! Wait 30 seconds, then open http://localhost:3000

Option 2: Clone First

git clone <repository-url>
cd kobizo
docker compose up -d

After starting:

• App: http://localhost:3000
• Directus Admin: http://localhost:8055 (admin@kobizo.de / kobizo2025)

What happens automatically:

• PostgreSQL database initialized
• Directus CMS configured with admin user
• Collections created (products, blog_posts)
• Sample data seeded (5 products, 3 blog posts)
• Public read permissions set
• API and web services started

Create a test account:

1. Go to http://localhost:3000/signup
2. Sign up with any email
3. Log in and start shopping

Stop and clean up:

docker compose down
docker volume rm kobizo_db_data kobizo_directus_uploads kobizo_directus_extensions

Development Mode

If you want to develop without Docker:

pnpm install

# Start database and CMS
docker compose up -d db directus seed

# In separate terminals:
pnpm --filter api dev    # API on :4000
pnpm --filter web dev    # Web on :3000

API

Auth

• POST /api/v1/auth/signup - Create account
• POST /api/v1/auth/login - Login
• POST /api/v1/auth/logout - Logout
• GET /api/v1/auth/me - Get user (protected)

Products

• GET /api/v1/products?page=1&limit=10&q=laptop&minPrice=0&maxPrice=100

Blog

• GET /api/v1/blog
• GET /api/v1/blog/:slug

Checkout (protected)

• POST /api/v1/checkout
• POST /api/v1/checkout/payment

Development

pnpm -r test        # Run all tests (11 total)
pnpm -r typecheck   # TypeScript check
pnpm -r lint        # ESLint

Structure

api/          # Express gateway
  src/
    auth/     # Auth controllers
    products/
    blog/
    checkout/ # Stock validation
    middleware/
    services/ # Directus client
    utils/    # JWT, logger, security

web/          # Next.js app
  app/        # Pages
  components/
  lib/        # Zustand store

shared/       # Types, schemas, constants

Troubleshooting

Directus not starting

• Check: docker ps and docker compose logs directus
• Verify database credentials in .env

Products not showing

• Check Directus has products with status=published and stock_quantity>0
• Verify public read permissions enabled

Auth issues

• Clear cookies
• Check JWT_SECRET is 32+ characters

Port in use

lsof -ti:3000 | xargs kill -9  # Web
lsof -ti:4000 | xargs kill -9  # API

Environment

Check .env.example for all variables. Key ones:

DIRECTUS_URL=http://localhost:8055
DIRECTUS_ADMIN_EMAIL=admin@kobizo.de
DIRECTUS_ADMIN_PASSWORD=your-password

JWT_SECRET=your-secret-min-32-chars
NEXT_PUBLIC_API_URL=http://localhost:4000

Test Card

Card: 4111111111111111 | Expiry: 12/25 | CVV: 123