Backend Implementation: From ‘It Works on My Machine’ to Production-Ready API

Frontend (React Native) → Backend (Node.js/Express/TypeScript)
├── 🔐 AWS Cognito (Authentication)
├── 📸 AWS S3 (File Storage)  
├── 👁️ Textract (OCR)
└── 🗄️ PostgreSQL + Prisma (Database)

npm init -y
# Core dependencies
npm install express cors helmet morgan dotenv joi multer prisma @prisma/client
npm install @aws-sdk/client-s3 @aws-sdk/client-textract aws-jwt-verify

# TypeScript setup
npm install -D typescript @types/node @types/express tsx nodemon jest

backend/src/
├── controllers/     # Request handlers
├── middleware/      # Auth, validation
├── routes/         # API endpoints
├── services/       # Business logic
├── config/         # Settings
├── types/          # TypeScript definitions
└── utils/          # Helpers

// src/services/cognitoService.ts
import { CognitoJwtVerifier } from 'aws-jwt-verify';

class CognitoService {
  private verifier = CognitoJwtVerifier.create({
    userPoolId: config.aws.cognito.userPoolId,
    tokenUse: 'access',
    clientId: config.aws.cognito.clientId,
  });

  async verifyToken(token: string): Promise<any> {
    return await this.verifier.verify(token); // ✨ Magic
  }

  async getOrCreateUser(cognitoPayload: any): Promise<any> {
    const { sub: cognitoId, email, given_name, family_name } = cognitoPayload;

    let user = await prisma.user.findUnique({ where: { cognitoId } });
    if (!user) {
      user = await prisma.user.create({
        data: { cognitoId, email, firstName: given_name, lastName: family_name }
      });
    }
    return user;
  }
}

// src/services/s3Service.ts
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

class S3Service {
  private s3Client = new S3Client({ /* config */ });

  async uploadFile(file: UploadedFile, key: string): Promise<string> {
    const command = new PutObjectCommand({
      Bucket: config.aws.s3.bucket,
      Key: key,
      Body: file.buffer,
      ContentType: file.mimetype,
    });

    await this.s3Client.send(command);
    return `https://${config.aws.s3.bucket}.s3.amazonaws.com/${key}`;
  }

  generateFileKey(userId: string, originalName: string): string {
    const timestamp = Date.now();
    const sanitized = originalName.replace(/[^a-zA-Z0-9.-]/g, '_');
    return `receipts/${userId}/${timestamp}_${sanitized}`;
  }
}

// src/services/textractService.ts
import { TextractClient, AnalyzeDocumentCommand } from '@aws-sdk/client-textract';

class TextractService {
  private textractClient = new TextractClient({ /* config */ });

  async analyzeExpense(s3Key: string): Promise<any> {
    const command = new AnalyzeDocumentCommand({
      Document: { S3Object: { Bucket: config.aws.s3.bucket, Name: s3Key } },
      FeatureTypes: ['FORMS', 'TABLES'],
    });

    const response = await this.textractClient.send(command);
    return this.parseExpenseData(response);
  }

  private extractTotalAmount(blocks: TextractBlock[]): number | null {
    const patterns = [/total.*?[\$]?(\d+\.\d{2})/i, /[\$](\d+\.\d{2})/];

    for (const block of blocks.filter(b => b.BlockType === 'LINE')) {
      for (const pattern of patterns) {
        const match = block.Text?.match(pattern);
        if (match) return parseFloat(match[1]);
      }
    }
    return null; // Sometimes receipts are mysterious 🤷‍♂️
  }
}

// prisma/schema.prisma
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  cognitoId String   @unique
  firstName String?
  lastName  String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  receipts  Receipt[]
  purchases Purchase[]
}

model Receipt {
  id           String        @id @default(cuid())
  userId       String
  originalName String
  s3Key        String        @unique
  s3Url        String?
  status       ReceiptStatus @default(UPLOADED)
  extractedData Json?        // OCR results
  createdAt    DateTime      @default(now())

  user     User      @relation(fields: [userId], references: [id])
  purchase Purchase?
}

enum ReceiptStatus {
  UPLOADED | PROCESSING | PROCESSED | FAILED
}

// src/routes/receipts.ts
import { Router } from 'express';
import receiptController from '@/controllers/receiptController';
import cognitoAuth from '@/middleware/cognitoAuth';
import { upload } from '@/middleware/upload';

const router: Router = Router();

router.post('/upload', cognitoAuth, upload.single('receipt'), receiptController.uploadReceipt);
router.get('/', cognitoAuth, receiptController.getReceipts);
router.get('/:id', cognitoAuth, receiptController.getReceiptById);
router.delete('/:id', cognitoAuth, receiptController.deleteReceipt);

export default router;

// src/middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';

const errorHandler = (error: any, req: Request, res: Response, next: NextFunction): void => {
  console.error('Error:', error);

  if (error instanceof AppError) {
    res.status(error.status).json({
      success: false,
      code: error.code,
      message: error.message,
      timestamp: new Date().toISOString()
    });
    return;
  }

  // Prisma errors
  if (error.code?.startsWith('P')) {
    const status = error.code === 'P2002' ? 409 : 404; // Duplicate : Not found
    res.status(status).json({
      success: false,
      code: error.code === 'P2002' ? 'DUPLICATE_RECORD' : 'RECORD_NOT_FOUND',
      message: 'Database operation failed',
      timestamp: new Date().toISOString()
    });
    return;
  }

  // Default error
  res.status(500).json({
    success: false,
    code: 'INTERNAL_ERROR',
    message: 'Something went wrong',
    timestamp: new Date().toISOString()
  });
};

// tests/routes/receipts.test.ts
import request from 'supertest';
import app from '@/app';

describe('POST /api/receipts/upload', () => {
  test('should upload receipt successfully', async () => {
    const response = await request(app)
      .post('/api/receipts/upload')
      .set('Authorization', `Bearer valid-token`)
      .attach('receipt', 'tests/fixtures/receipt.jpg')
      .expect(201);

    expect(response.body.success).toBe(true);
    expect(response.body.data).toHaveProperty('id');
  });

  test('should reject unauthorized upload', async () => {
    await request(app)
      .post('/api/receipts/upload')
      .attach('receipt', 'tests/fixtures/receipt.jpg')
      .expect(401);
  });
});

✅ Environment variables configured
✅ Database migrations run  
✅ TypeScript compilation successful
✅ AWS services configured
✅ Tests passing
✅ SSL enabled
✅ CORS configured

NODE_ENV=production
DATABASE_URL=postgresql://user:pass@host:5432/db
AWS_COGNITO_USER_POOL_ID=us-east-1_xxxxxxxxx
AWS_S3_BUCKET=purchase-tracker-receipts
AWS_REGION=us-east-1