🏗️ [Day 1 - Hour 3] Project Structure & Application Scaffolding

[uozopio]

📋 Task Overview

Sprint Day: Day 1 - Morning Session
Time Slot: 11:00 - 12:00 (1 hour)
Task Type: Collaborative Project Setup (All Team Members)
Estimated Duration: 1 hour
Dependencies: Database Schema (Issue #3)

🎯 Objectives

Create the escrow application structure within the Zopio monorepo, set up API routes skeleton, configure Next.js with internationalization support, and prepare the shadcn/ui component library for development.

📝 Detailed Requirements

1. Create Escrow App Structure

• Create new app in apps/escrow directory
• Set up Next.js 14+ app structure with:
  • app/ directory for App Router
  • components/ for React components
  • lib/ for utilities and helpers
  • services/ for business logic
  • hooks/ for custom React hooks
  • types/ for TypeScript definitions
  • constants/ for app constants
• Configure next.config.js with proper settings
• Set up tsconfig.json with path aliases
• Create base layout structure in app/layout.tsx

2. API Routes Skeleton

• Create API route structure under app/api/:
  • /api/escrow/ - Escrow transaction endpoints
    • create/route.ts - Create new escrow
    • [id]/route.ts - Get/update specific escrow
    • [id]/status/route.ts - Update escrow status
  • /api/payment/ - Payment processing endpoints
    • create/route.ts - Initialize payment
    • webhook/route.ts - Payment gateway webhooks
    • verify/route.ts - Verify payment status
  • /api/user/ - User management endpoints
    • profile/route.ts - User profile management
    • verify/route.ts - User verification
  • /api/otp/ - OTP verification endpoints
    • send/route.ts - Send OTP
    • verify/route.ts - Verify OTP code
  • /api/document/ - Document management endpoints
    • upload/route.ts - File upload
    • [id]/route.ts - Get/delete document
  • /api/admin/ - Admin endpoints
    • transactions/route.ts - List all transactions
    • disputes/route.ts - Manage disputes
• Add placeholder handlers with proper TypeScript types
• Implement basic error handling structure

3. Internationalization Setup

• Install and configure next-intl for i18n support
• Create locale structure:
  • /locales/tr/ - Turkish translations
  • /locales/en/ - English translations
• Set up translation files for:
  • common.json - Common UI elements
  • forms.json - Form labels and validation messages
  • escrow.json - Escrow-specific terms
  • errors.json - Error messages
• Configure middleware for locale detection
• Implement language switcher component
• Set up locale routing (/tr, /en)

4. shadcn/ui Component Setup

• Initialize shadcn/ui with pnpm dlx shadcn-ui@latest init
• Configure theme with brand colors
• Install essential components:
  • Button, Input, Label, Textarea
  • Select, Checkbox, Radio Group
  • Card, Dialog, Alert, Toast
  • Form (with react-hook-form integration)
  • Tabs, Accordion, Progress
  • Table, Badge, Avatar
  • Skeleton (for loading states)
• Create components.json configuration
• Set up dark mode support with next-themes
• Create base component exports in components/ui/index.ts

🔧 Technical Context

Project Structure Best Practices

• Separation of Concerns: Clear separation between UI, business logic, and data access
• Type Safety: Full TypeScript coverage with strict mode
• Code Organization: Feature-based organization within components
• Reusability: Shared components in the monorepo packages
• Testing Structure: Parallel test files for easy testing

API Design Principles

• RESTful conventions for resource endpoints
• Consistent error responses with proper HTTP status codes
• Request validation using Zod schemas
• Rate limiting preparation for production
• CORS configuration for frontend-backend communication

Internationalization Requirements

• RTL Support: Prepare for potential Arabic language addition
• Number Formatting: Turkish and English number formats
• Date Formatting: Locale-specific date displays
• Currency Display: TRY and USD support
• Dynamic Loading: Lazy load translations for performance

✅ Acceptance Criteria

• Escrow app runs independently with pnpm dev --filter escrow
• All API route placeholders return proper responses
• Language switching works between Turkish and English
• All shadcn/ui components are properly styled
• TypeScript compilation passes without errors
• Project structure follows Zopio conventions
• Hot reload works for all file types

👥 Team Assignments

All Team Members:

• @uozopio (Umut) - API routes structure and service layer setup
• @mbyzopio (Burak) - Page structure and form component scaffolding
• @teczopio (Enes) - UI components installation and theming

---

This task is part of the 2-day MVP sprint for the Paylox Escrow System