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

This content originally appeared on DEV Community and was authored by Artem Gontar

Time to build the brain of our Purchase Tracker! While our React Native app looks pretty, it needs something to talk to — enter our Node.js TypeScript backend. Think of it as the reliable friend who remembers everything and never loses your receipts.

Why Node.js + TypeScript? Because Type Safety is Life

With Node.js + TypeScript, we get JavaScript everywhere plus compile-time error catching. No more “undefined is not a function” surprises in production.

Our stack:

Node.js + Express + TypeScript — Type-safe web framework
AWS Cognito — Authentication superhero
PostgreSQL + Prisma — Relational database with modern ORM
AWS S3 + Textract — Cloud storage and OCR
Jest + Supertest — Testing squad

The Architecture

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

Quick Setup

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

Project structure:

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

Authentication: AWS Cognito Magic

No more password hashing nightmares. Cognito handles auth so we focus on business logic.

// 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;
  }
}

File Upload: S3 Made Simple

// 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}`;
  }
}

Simple workflow: Upload → Generate unique key → Store in S3 → Return URL

OCR Magic: Textract Reads Receipts

// 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 🤷‍♂
  }
}

Database: PostgreSQL + Prisma = Type Safety + Reliability

// 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
}

Why PostgreSQL + Prisma rocks:

Strong typing — Catch errors at compile time
Relational integrity — Proper foreign keys
Type-safe client — Auto-generated TypeScript types
Migration system — Version control for schema

API Routes: Clean & RESTful

// 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;

Clean endpoints:

POST /api/receipts/upload — Upload receipt image
GET /api/receipts — List all receipts
GET /api/receipts/:id — Get specific receipt
GET /api/purchases — List purchases
GET /api/users/profile — User profile

Error Handling: When Things Go Wrong

// 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()
  });
};

Testing: Proving It Works

// 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);
  });
});

What we test: Happy paths, error cases, auth flows, edge cases.

Deployment Checklist

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

Key environment variables:

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

What We Built

A backend that:

Scales (handles real traffic)
Type-safe (catches errors early)
Secure (Cognito handles auth)
Reliable (proper error handling)
Maintainable (clean structure + TypeScript)
Fast (optimized queries + caching)

TL;DR: Node.js + TypeScript + AWS + PostgreSQL + Prisma = Backend that makes you look like a rockstar

Stack: Node.js, Express, TypeScript, AWS Cognito, S3, Textract, PostgreSQL, Prisma, Jest

Architecture: Type-safe RESTful API with JWT auth, file processing, OCR integration, and modern best practices.

This content originally appeared on DEV Community and was authored by Artem Gontar