Developer Guide

Ratio Tuta is built with modern web technologies for performance, scalability, and developer experience.

Tech Stack

Project Structure

ratio-tuta/
                          ├── src/
                          │   ├── app/                  # Next.js 15 App Router
                          │   │   ├── api/             # API endpoints
                          │   │   ├── auth/            # Authentication pages
                          │   │   ├── dashboard/       # Admin dashboard
                          │   │   ├── cash-register/   # POS interface
                          │   │   └── docs/            # Documentation
                          │   ├── components/          # React components
                          │   │   ├── admin-zone/      # Admin UI components
                          │   │   ├── cash-register/   # POS components
                          │   │   └── ui/              # Reusable UI elements
                          │   ├── lib/                 # Utility libraries
                          │   │   ├── api-client.ts    # CSRF-enabled API wrapper
                          │   │   ├── auth.ts          # Authentication helpers
                          │   │   ├── csrf.ts          # CSRF token generation
                          │   │   ├── session.ts       # Session management
                          │   │   └── prisma.ts        # Database client
                          │   └── hooks/               # Custom React hooks
                          ├── prisma/
                          │   └── schema.prisma        # Database schema
                          ├── lib/                     # Shared backend utilities
                          ├── public/                  # Static assets
                          └── messages/                # i18n translations

Design Patterns

• Server Components: Default for data fetching and SSR
• Client Components: Only when needed for interactivity
• API Route Handlers: RESTful endpoints in /app/api
• Middleware: Session validation, CSRF, rate limiting
• Custom Hooks: Reusable stateful logic (e.g., useCsrfToken)
• Repository Pattern: Database operations abstracted via Prisma

PostgreSQL database managed with Prisma ORM for type-safe queries and migrations.

Core Models

model User {
                        id              String    @id @default(cuid())
                        email           String    @unique
                        emailHmac       String    @unique  // HMAC for lookups
                        emailEncrypted  String            // AES-256-GCM encrypted
                        passwordHash    String
                        firstName       String
                        lastName        String
                        role            Role      @default(USER)
                        emailVerified   Boolean   @default(false)
                        avatarUrl       String?
                        createdAt       DateTime  @default(now())
                      }

model Team {
                        id          String         @id @default(cuid())
                        name        String
                        ownerId     String
                        members     TeamMember[]
                        places      Place[]
                        items       Item[]
                        plan        SubscriptionPlan @default(FREE)
                      }

                      model TeamMember {
                        id       String   @id @default(cuid())
                        teamId   String
                        userId   String
                        role     TeamRole @default(MEMBER)
                      }

model Place {
                      id          String    @id @default(cuid())
                      teamId      String
                      name        String
                      address1    String?
                      city        String?
                      country     String?
                      timezone    String?
                      currency    String    @default("EUR")
                      isActive    Boolean   @default(true)
                      receipts    Receipt[]
                      createdAt   DateTime  @default(now())
                    }

model Item {
                      id              String          @id @default(cuid())
                      teamId          String
                      name            String
                      sku             String?
                      price           Float
                      pricePaid       Float?
                      taxRateBps      Int             // Basis points (100 = 1%)
                      imageUrl        String
                      measurementType MeasurementType @default(PCS)
                      stockQuantity   Float           @default(0)
                      categoryId      String?
                      isActive        Boolean         @default(true)
                    }

model Receipt {
                      id            String        @id @default(cuid())
                      placeId       String
                      userId        String
                      totalAmount   Float
                      taxAmount     Float
                      amountGiven   Float
                      changeAmount  Float
                      paymentOption PaymentOption
                      lineItems     ReceiptLineItem[]
                      createdAt     DateTime      @default(now())
                    }

                    model ReceiptLineItem {
                      id          String  @id @default(cuid())
                      receiptId   String
                      itemId      String
                      quantity    Float
                      unitPrice   Float
                      totalPrice  Float
                      taxRateBps  Int
                    }

Database Operations

// Run migrations
                  npm run prisma:migrate

                  // Generate Prisma Client
                  npm run prisma:generate

                  // Open Prisma Studio (GUI)
                  npm run prisma:studio

                  // Reset database (development only!)
                  npm run prisma:reset

RESTful API built with Next.js 15 API Routes. All endpoints require authentication unless marked as public.

Authentication Endpoints

// Request
{ "email": "user@example.com", "password": "***", "remember": true }

// Response
{ "id": "...", "email": "...", "role": "USER" }

// Request
{ "name": "John Doe", "email": "...", "password": "...", "teamName": "..." }

// Response
{ "message": "Account created. Please verify your email." }

Resource Endpoints

Using the API Client

Frontend uses a CSRF-enabled API wrapper:

import { api, ApiError } from '@/lib/api-client'

                  // GET request (no CSRF needed)
                  const data = await api.get('/api/places')

                  // POST request (CSRF auto-included)
                  const newPlace = await api.post('/api/places', {
                    name: 'New Store',
                    currency: 'EUR'
                  })

                  // PATCH request
                  const updated = await api.patch('/api/places/123', {
                    name: 'Updated Name'
                  })

                  // DELETE request
                  await api.delete('/api/places/123')

                  // Error handling
                  try {
                    await api.post('/api/places', data)
                  } catch (err) {
                    if (err instanceof ApiError) {
                      console.error(err.message, err.status)
                    }
                  }

Comprehensive security implementation following OWASP guidelines and industry best practices.

CSRF Protection

// Backend validation
                  import { requireCsrfToken } from '@lib/csrf'

                  export async function POST(req: Request) {
                    const session = await getSession()
                    requireCsrfToken(req, session) // Throws if invalid
                    // ... handle request
                  }

Authentication & Sessions

• Password Hashing: bcrypt with 12 rounds
• Password Requirements: 8-128 characters, complexity checks
• Pwned Password Check: k-Anonymity API integration
• Session Cookies: HttpOnly, Secure, SameSite=Strict, __Host- prefix
• Session Storage: iron-session with AES-256-GCM encryption
• Email Verification: Required for account activation

Data Protection

Security Headers

// next.config.ts
                  headers: [
                    { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
                    { key: 'X-Content-Type-Options', value: 'nosniff' },
                    { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
                    { key: 'Permissions-Policy', value: 'geolocation=(), microphone=()' },
                    {
                      key: 'Content-Security-Policy',
                      value: "default-src 'self'; img-src 'self' data: https://*.amazonaws.com;"
                    },
                    {
                      key: 'Strict-Transport-Security',
                      value: 'max-age=63072000; includeSubDomains; preload'
                    }
                  ]

Rate Limiting

• Authentication: 5 attempts per 15 minutes per IP
• API Endpoints: Sliding window algorithm
• Storage: Upstash Redis (distributed)
• Response Headers: X-RateLimit-* for debugging

Audit Logging

All security-sensitive actions are logged:

import { logAudit } from '@lib/logger'

                await logAudit({
                  action: 'user.login.success',
                  status: 'SUCCESS',
                  userId: user.id,
                  metadata: { ip: req.ip }
                })

Deploy to production with Vercel, PostgreSQL, and AWS services.

Environment Variables

Required environment variables (see .env.example):

# Database
                      DATABASE_URL="postgresql://..."

                      # Sessions
                      SESSION_SECRET="strong-random-secret-min-32-chars"

                      # AWS S3 (file uploads)
                      AWS_ACCESS_KEY_ID="..."
                      AWS_SECRET_ACCESS_KEY="..."
                      AWS_REGION="us-east-1"
                      AWS_S3_BUCKET="ratio-tuta-files"

                      # Email (Resend)
                      RESEND_API_KEY="re_..."
                      RESEND_FROM_EMAIL="noreply@yourdomain.com"

                      # Redis (rate limiting)
                      UPSTASH_REDIS_REST_URL="https://..."
                      UPSTASH_REDIS_REST_TOKEN="..."

                      # App
                      NEXT_PUBLIC_APP_URL="https://yourdomain.com"
                      NODE_ENV="production"

Deployment Steps

1. Set up PostgreSQL database

   # Use Vercel Postgres, Supabase, or any PostgreSQL provider
                         # Run migrations
                         npx prisma migrate deploy

2. Configure AWS S3 bucket
   • Create bucket with private access
   • Configure CORS for your domain
   • Create IAM user with S3 permissions
3. Set up Redis (Upstash)

   # Create Redis database at upstash.com
                           # Copy REST URL and token to env vars

4. Deploy to Vercel

   # Install Vercel CLI
                           npm i -g vercel
   
                           # Deploy
                           vercel --prod
   
                           # Or connect GitHub repo for auto-deploys

5. Set environment variables in Vercel dashboard
6. Configure custom domain

Production Checklist

• Database migrations applied
• All environment variables set
• SESSION_SECRET is cryptographically strong (32+ chars)
• HTTPS enabled (automatic with Vercel)
• Email sending configured and tested
• S3 bucket CORS configured for your domain
• Rate limiting enabled (Upstash Redis connected)
• Audit logging reviewed
• Error monitoring configured (Sentry, etc.)

Monitoring

• Vercel Analytics: Performance and usage metrics
• Database: Monitor connection pool, query performance
• Redis: Check rate limit hits, cache performance
• S3: Monitor storage usage and costs
• Logs: Review audit logs for security events