Files
Suman/docs/implementation-plan/phase-01-infrastructure-and-monorepo.md
Nermin Karic f5e2fcbf98 first commit
2026-11-22 21:49:17 +01:00

5.0 KiB

Faza 1: Infrastruktura, Monorepo i Baza Podataka

1.1. Svrha i Ciljevi Faze

Cilj prve faze je postavljanje stabilnog, lokalnog i produkcijski orijentisanog razvojnog okruženja. Uspostavlja se baza podataka PostgreSQL 16 i Redis 7 kroz Docker Compose, te konfiguriše Turborepo monorepo koji orkestrira Medusa v2 backend i dva odvojena Next.js storefronta.


1.2. Zvanični Paketi i Alati

Sistem se oslanja isključivo na provjereni softverski stek:

  • Node.js: verzija >= 22.0.0
  • Package Manager: pnpm (preporučeno) ili npm (verzija >= 10.0.0)
  • Docker & Docker Compose: za pokretanje PostgreSQL 16 i Redis 7
  • Turborepo: verzija ^2.0.0 za orkestraciju monorepo taskova (dev, build, lint)

1.3. Konfiguracija Baze i Keša (docker-compose.yml)

Kreirajte ili ažurirajte datoteku docker-compose.yml u korijenu repozitorijuma (suman-doo/docker-compose.yml):

version: "3.8"

services:
  postgres:
    image: postgres:16-alpine
    container_name: umbrella_postgres
    restart: always
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-medusa_user}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-medusa_password}
      POSTGRES_DB: ${POSTGRES_DB:-medusa_umbrella}
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U medusa_user -d medusa_umbrella"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: umbrella_redis
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  pgdata:
  redisdata:

1.4. Turborepo Konfiguracija

Root package.json

U korijenu monorepoa definisani su radni prostori (workspaces) i skripte za simultano pokretanje servisa:

{
  "name": "umbrella-platform",
  "private": true,
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": ">=22.0.0"
  },
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "lint": "turbo lint",
    "backend:dev": "turbo dev --filter=@dtc/backend",
    "backend:seed": "turbo seed --filter=@dtc/backend",
    "store-de:dev": "turbo dev --filter=@umbrella/storefront-de",
    "store-at:dev": "turbo dev --filter=@umbrella/storefront-at"
  },
  "devDependencies": {
    "prettier": "^3.3.0",
    "turbo": "^2.0.14"
  },
  "workspaces": [
    "apps/*"
  ]
}

Root turbo.json

Optimizovana definicija taskova sa cachingom i varijablama okruženja:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", ".medusa/**", "dist/**"],
      "env": [
        "DATABASE_URL",
        "REDIS_URL",
        "MEDUSA_BACKEND_URL",
        "NEXT_PUBLIC_MEDUSA_BACKEND_URL",
        "NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY"
      ]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "seed": {
      "cache": false
    }
  }
}

1.5. Konfiguracija Backend Okruženja (apps/backend/.env)

U datoteci apps/backend/.env definisani su konekcioni stringovi i sigurnosni tokeni:

# Port na kojem se izvršava Medusa v2 Backend i Admin
PORT=9000

# Baza podataka (PostgreSQL 16)
DATABASE_URL=postgres://medusa_user:medusa_password@localhost:5432/medusa_umbrella

# Redis za Event Bus i Keširanje sesija
REDIS_URL=redis://localhost:6379

# JWT i Cookie Tajne (Za produkciju generisati jake ključeve sa: openssl rand -base64 32)
JWT_SECRET=super_secret_jwt_key_suncobrani_2026_production_grade
COOKIE_SECRET=super_secret_cookie_key_suncobrani_2026_production_grade

# CORS Konfiguracija - dozvola pristupa za Admin i oba Storefronta
STORE_CORS=http://localhost:8000,http://localhost:8001
ADMIN_CORS=http://localhost:9000,http://localhost:7001
AUTH_CORS=http://localhost:9000,http://localhost:8000,http://localhost:8001

# Eksterni CRM Webhook (HubSpot / Brevo)
CRM_WEBHOOK_URL=https://api.hubspot.com/v1/webhook/umbrella-orders
CRM_API_KEY=pat-eu1-dummy-key-for-crm-sync

1.6. Korak-po-Korak Instrukcije za Izvršavanje

  1. Pokretanje Docker kontejnera:
    docker compose up -d
    
  2. Provjera statusa kontejnera:
    docker compose ps
    
    Oba servisa (umbrella_postgres i umbrella_redis) moraju imati status healthy ili running.
  3. Instalacija zavisnosti u monorepou:
    pnpm install
    
  4. Pokretanje migracija na backendu:
    cd apps/backend
    npx medusa db:migrate
    

1.7. Kriterijumi Prihvatljivosti (Acceptance Criteria)

  • PostgreSQL kontejner uspješno odgovara na portu 5432 i baza medusa_umbrella je kreirana.
  • Redis kontejner uspješno odgovara na komandu redis-cli ping sa PONG.
  • Medusa v2 migracije (npx medusa db:migrate) prolaze sa izlaznim kodom 0 bez grešaka.
  • Turborepo komanda pnpm dev uspješno detektuje radne prostore u apps/*.