RawDrive/
├── packages/              # Shared npm packages (pnpm workspace)
│   ├── shared-types/      # @rawdrive/shared-types - Domain enums & types
│   ├── shared-constants/  # @rawdrive/shared-constants - Config values
│   ├── shared-validation/ # @rawdrive/shared-validation - Zod schemas
│   └── shared-utils/      # @rawdrive/shared-utils - Date/format utils
│
├── frontend/              # React 19 + Vite + TypeScript
│   ├── src/
│   │   ├── components/    # React components
│   │   │   ├── ui/        # Design system (AppButton, AppInput, etc.)
│   │   │   ├── layout/    # Layout components (Header, Sidebar, etc.)
│   │   │   └── features/  # Feature-specific components (gallery/, upload/, etc.)
│   │   ├── pages/         # Page components (route handlers)
│   │   │   ├── public/    # Public pages (SignIn, SignUp, etc.)
│   │   │   ├── workspace/ # Authenticated workspace pages
│   │   │   └── onboarding/ # Onboarding flow pages
│   │   ├── hooks/         # Custom React hooks (useUpload, useGallery, etc.)
│   │   ├── services/      # API clients (api.ts, auth.ts, etc.)
│   │   ├── contexts/      # React contexts (AuthContext, etc.)
│   │   ├── router/        # React Router configuration
│   │   ├── config/        # Configuration (featureFlags.ts, etc.)
│   │   ├── utils/         # Utility functions
│   │   ├── constants/     # Frontend-specific constants
│   │   └── styles/        # Global styles
│   └── public/            # Static assets (favicon, images, etc.)
│
├── backend/               # Python 3.11 + FastAPI
│   ├── src/app/
│   │   ├── api/           # API route handlers
│   │   │   ├── v1/        # Versioned API routes (auth.py, galleries.py, etc.)
│   │   │   └── dependencies/ # FastAPI dependencies
│   │   ├── services/      # Business logic (NEVER put in models/)
│   │   ├── repositories/  # Database access layer (queries only)
│   │   ├── models/        # SQLAlchemy models (database schema ONLY)
│   │   ├── middleware/    # FastAPI middleware
│   │   ├── config/        # Configuration modules
│   │   ├── utils/         # Utility functions
│   │   ├── shared/        # Generated Python types from @rawdrive/shared-*
│   │   └── workers/       # Background job workers (Celery tasks)
│   ├── migrations/        # Alembic migrations
│   │   └── versions/      # Migration files (0001_*, 0002_*, etc.)
│   └── tests/             # pytest tests
│
├── services/              # Microservices (6 services)
│   ├── billing-service/   # Payment processing (Stripe/Razorpay)
│   │   ├── src/
│   │   │   ├── api/v1/    # API endpoints (subscription.py, webhooks.py)
│   │   │   ├── services/  # Business logic (subscription_service.py, razorpay_service.py)
│   │   │   ├── repositories/ # Database access
│   │   │   ├── schemas/   # Pydantic schemas
│   │   │   ├── middleware/ # Service middleware
│   │   │   ├── utils/     # JWT validation, etc.
│   │   │   ├── config.py  # Service configuration
│   │   │   └── main.py    # FastAPI entry point
│   │   ├── tests/
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   │
│   ├── gallery-service/   # High-performance gallery viewing (50K concurrent)
│   │   ├── src/
│   │   │   ├── api/v1/    # galleries.py, magic_links.py, websocket.py
│   │   │   ├── services/  # gallery_service.py, proofing_service.py
│   │   │   ├── cache/     # Redis client
│   │   │   ├── observability/ # Metrics, health checks
│   │   │   └── middleware/ # Rate limiting, correlation IDs
│   │   ├── tests/
│   │   │   ├── unit/
│   │   │   ├── integration/
│   │   │   └── load/
│   │   └── ...
│   │
│   ├── upload-service/    # TUS resumable uploads with chunking
│   │   ├── src/app/
│   │   │   ├── api/v1/    # upload.py
│   │   │   ├── services/  # upload_service.py, chunked_upload_service.py, encryption_service.py
│   │   │   ├── core/      # config.py, database.py, redis.py
│   │   │   ├── middleware/ # auth.py, rate_limit.py
│   │   │   ├── observability/ # logging.py, metrics.py
│   │   │   └── resilience/ # circuit_breaker.py
│   │   └── ...
│   │
│   ├── onboarding-service/ # User registration & workspace setup
│   │   ├── src/
│   │   │   ├── api/v1/    # onboarding.py
│   │   │   ├── services/  # onboarding_service.py
│   │   │   ├── repositories/ # onboarding_repository.py
│   │   │   └── schemas/   # onboarding.py
│   │   └── ...
│   │
│   ├── invitations-service/ # Digital wedding invitations
│   │   ├── src/
│   │   │   ├── api/v1/    # invitations.py, rsvp.py, guests.py
│   │   │   ├── services/  # invitation_service.py, email_service.py
│   │   │   └── shared/    # Generated Python types
│   │   └── ...
│   │
│   └── workspace-service/ # Workspace management (PARTIAL - under development)
│       ├── src/
│       └── tests/
│
├── infrastructure/        # Docker, Kubernetes, Traefik, monitoring
│   ├── docker/            # Docker Compose configurations
│   │   ├── docker-compose.yml        # Main stack (includes Traefik)
│   │   ├── docker-compose.dev.yml    # Development stack
│   │   ├── docker-compose.traefik.yml # DEPRECATED - DO NOT USE
│   │   ├── traefik/       # Traefik v3 configuration
│   │   │   ├── traefik.yaml  # Main config
│   │   │   └── dynamic.yaml  # Dynamic routing (single source of truth)
│   │   └── init/          # Initialization scripts
│   │
│   ├── kubernetes/        # Kubernetes manifests
│   │   └── base/
│   │       ├── backend/
│   │       ├── billing-service/
│   │       ├── gallery-service/
│   │       ├── upload-service/
│   │       ├── traefik/   # Traefik IngressRoutes
│   │       └── keda/      # KEDA ScaledObjects
│   │
│   └── monitoring/        # Prometheus, Grafana, Loki configs
│       ├── prometheus/
│       │   ├── prometheus.yaml
│       │   ├── alerts.yaml
│       │   └── traefik-alerts.yaml
│       └── grafana/
│           └── dashboards/
│               └── traefik-keda.json
│
├── scripts/               # Build and utility scripts
│   ├── generate-python-types.ts  # TypeScript → Python generator
│   ├── dev-gallery-service.sh    # Gallery service dev mode
│   └── dev-billing-service.sh    # Billing service dev mode
│
├── docs/                  # Documentation (150+ files)
│   ├── Features/          # Feature documentation
│   ├── Business_Features/ # Business feature specs (numbered 01-24)
│   ├── project/           # Project documentation (tech stack, roadmap)
│   ├── runbooks/          # Operational runbooks
│   └── troubleshooting/   # Troubleshooting guides
│
├── specs/                 # Feature specifications (17+ specs)
│   ├── 001-admin-microservice/
│   ├── 002-user-profile-settings/
│   └── ...
│
├── tests/                 # E2E Playwright tests
│   ├── login.spec.ts
│   ├── traefik-routing.spec.ts
│   └── verification/
│
└── .claude/               # Claude Code skills
    ├── skills/            # 20 development skills
    │   ├── accessibility/
    │   ├── infrastructure/
    │   ├── project-structure/
    │   └── ...
    └── settings.json

# Frontend
cd frontend && npm run dev         # Vite dev server (localhost:3000)
cd frontend && npm run build       # Production build
cd frontend && npm test            # Vitest tests

# Backend
cd backend && uvicorn src.app.main:app --reload  # Dev server (localhost:8000)
cd backend && pytest               # pytest tests
cd backend && pytest --cov=src     # with coverage

# Microservices (dev mode)
bash scripts/dev-gallery-service.sh    # Gallery service (port 8004)
bash scripts/dev-billing-service.sh    # Billing service (port 8006)

# Full stack (Docker)
docker compose -f infrastructure/docker/docker-compose.yml up -d
docker compose -f infrastructure/docker/docker-compose.dev.yml up -d  # Dev mode

cd backend

# Run migrations
alembic upgrade head

# Create new migration (auto-generate from models)
alembic revision --autogenerate -m "description"

# Rollback one migration
alembic downgrade -1

# Install dependencies for all packages
pnpm install

# Build all shared packages
pnpm build:packages

# Generate Python types from TypeScript
pnpm generate:python

# Test shared packages
pnpm test:packages

# Run cross-platform type parity tests
pnpm test:parity

// 1. External imports
import React, { useState } from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. Shared packages (preferred for cross-platform types)
import { InvitationStatus, GalleryStatus } from '@rawdrive/shared-types';
import { API_BASE, PAGINATION, FILE_TYPES } from '@rawdrive/shared-constants';
import { isValidHexColor, sanitizeHtml } from '@rawdrive/shared-validation';
import { formatRelativeDate, formatFileSize } from '@rawdrive/shared-utils';

// 3. Type imports (local)
import type { Gallery } from '@/types/gallery';

// 4. Services/hooks
import { useGallery } from '@/hooks/useGallery';

// 5. Components
import { AppButton } from '@/components/ui/AppButton';

# 1. Standard library
from typing import Optional, List
from uuid import UUID
from datetime import datetime

# 2. Third-party
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from pydantic import BaseModel, Field

# 3. Shared types (generated from TypeScript)
from app.shared.types import InvitationStatus, GalleryStatus
from app.shared.constants import API_BASE, PAGINATION
from app.shared.validation import is_valid_hex_color

# 4. Local imports
from app.services.gallery_service import GalleryService
from app.repositories.gallery_repository import GalleryRepository
from app.models.gallery import Gallery
from app.api.dependencies import get_db, get_current_user

// frontend/src/components/features/gallery/GalleryCard.tsx

import React, { memo } from 'react';
import { Gallery } from '@rawdrive/shared-types';
import { AppCard } from '@/components/ui/AppCard';
import { formatRelativeDate } from '@rawdrive/shared-utils';

interface GalleryCardProps {
  gallery: Gallery;
  onSelect: (gallery: Gallery) => void;
  workspaceId: string;  // ALWAYS include workspace context
}

export const GalleryCard = memo<GalleryCardProps>(({
  gallery,
  onSelect,
  workspaceId
}) => {
  return (
    <AppCard
      hoverable
      onClick={() => onSelect(gallery)}
      data-workspace-id={workspaceId}
    >
      <h3>{gallery.name}</h3>
      <p>{formatRelativeDate(gallery.created_at)}</p>
    </AppCard>
  );
});

GalleryCard.displayName = 'GalleryCard';

# backend/src/app/services/gallery_service.py

from typing import Optional, List
from uuid import UUID
from sqlalchemy.ext.asyncio import AsyncSession

from app.repositories.gallery_repository import GalleryRepository
from app.models.gallery import Gallery
from app.shared.types import GalleryStatus

class GalleryService:
    """
    Business logic for gallery management.

    CRITICAL: All methods MUST include workspace_id for multi-tenant isolation.
    """

    def __init__(self, db: AsyncSession):
        self.db = db
        self.repo = GalleryRepository(db)

    async def get_by_id(
        self,
        workspace_id: UUID,
        gallery_id: UUID
    ) -> Optional[Gallery]:
        """
        Get gallery by ID.

        Args:
            workspace_id: Workspace UUID (REQUIRED for isolation)
            gallery_id: Gallery UUID

        Returns:
            Gallery object or None
        """
        # ALWAYS include workspace_id in queries
        return await self.repo.get_by_id(workspace_id, gallery_id)

    async def list_galleries(
        self,
        workspace_id: UUID,
        status: Optional[GalleryStatus] = None,
        limit: int = 50,
        offset: int = 0
    ) -> List[Gallery]:
        """List galleries with pagination."""
        return await self.repo.list_galleries(
            workspace_id=workspace_id,
            status=status,
            limit=limit,
            offset=offset
        )

# backend/src/app/repositories/gallery_repository.py

from typing import Optional, List
from uuid import UUID
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from app.models.gallery import Gallery
from app.shared.types import GalleryStatus

class GalleryRepository:
    """
    Data access layer for galleries.

    ONLY database queries - NO business logic.
    """

    def __init__(self, db: AsyncSession):
        self.db = db

    async def get_by_id(
        self,
        workspace_id: UUID,
        gallery_id: UUID
    ) -> Optional[Gallery]:
        """
        Retrieve gallery by ID with workspace isolation.
        """
        result = await self.db.execute(
            select(Gallery)
            .where(
                Gallery.workspace_id == workspace_id,  # Multi-tenant isolation
                Gallery.id == gallery_id
            )
        )
        return result.scalar_one_or_none()

services/[service-name]/
├── src/
│   ├── api/v1/            # API endpoints
│   ├── services/          # Business logic
│   ├── repositories/      # Database access (if needed)
│   ├── schemas/           # Pydantic request/response models
│   ├── middleware/        # Service-specific middleware
│   ├── cache/             # Redis client
│   ├── observability/     # Metrics, health checks, logging
│   ├── utils/             # JWT validation, etc.
│   ├── config.py          # Service configuration
│   └── main.py            # FastAPI entry point
├── tests/
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── load/              # Load tests (optional)
├── Dockerfile
├── requirements.txt
└── README.md

# 1. Repository (database queries ONLY)
class GalleryRepository:
    async def get_by_id(self, workspace_id: UUID, gallery_id: UUID) -> Gallery:
        # SQL query

# 2. Service (business logic)
class GalleryService:
    def __init__(self, db: AsyncSession):
        self.repo = GalleryRepository(db)

    async def get_gallery(self, workspace_id: UUID, gallery_id: UUID) -> Gallery:
        # Business logic, validation, caching
        gallery = await self.repo.get_by_id(workspace_id, gallery_id)
        if not gallery:
            raise NotFoundException()
        return gallery

# 3. API (HTTP handling)
@router.get("/galleries/{gallery_id}")
async def get_gallery(
    gallery_id: UUID,
    service: GalleryService = Depends(),
    workspace_id: UUID = Depends(get_workspace_id)
):
    return await service.get_gallery(workspace_id, gallery_id)

# Each service validates JWT and extracts workspace_id
from app.utils.jwt import decode_jwt_token

async def get_workspace_id(token: str = Depends(get_jwt_token)) -> UUID:
    payload = decode_jwt_token(token, settings.JWT_SECRET)
    return UUID(payload["workspace_id"])

# Every query includes workspace_id
result = await db.execute(
    select(Gallery).where(Gallery.workspace_id == workspace_id)
)

# WRONG
backend/services/gallery_service.py  # Missing src/app/
frontend/GalleryCard.tsx             # Missing src/components/

# CORRECT
backend/src/app/services/gallery_service.py
frontend/src/components/features/gallery/GalleryCard.tsx

# WRONG (models should be pure SQLAlchemy)
class Gallery(Base):
    def calculate_total_size(self):
        # Business logic

# CORRECT (business logic in services)
class GalleryService:
    async def calculate_total_size(self, gallery_id: UUID):
        # Business logic

# WRONG (no multi-tenant isolation)
result = await db.execute(select(Gallery).where(Gallery.id == gallery_id))

# CORRECT
result = await db.execute(
    select(Gallery).where(
        Gallery.workspace_id == workspace_id,
        Gallery.id == gallery_id
    )
)

// WRONG
const API_URL = "http://localhost:8000";

// CORRECT
import { API_BASE } from '@rawdrive/shared-constants';