DEV Community: Tiani pekins Ebika

The 3-Tier Architecture of LocalHands: Engineering a Scalable Service Marketplace

Tiani pekins Ebika — Mon, 22 Jun 2026 19:14:27 +0000

Subtitle: How a split frontend/backend, a NestJS API layer, and a strict relational core hold up under fragmented infrastructure.

With the Prisma schema in place, the next question was what serves it. Below, I break down the three-tier architecture LocalHands runs on: how the layers are split and what each one is responsible for.

1. Why 3-Tiers, Two Repositories

LocalHands runs as two independent codebases, frontend and backend, each with its own repo, deployment pipeline, and release cycle. They talk over a REST API.

Figure 1: Client, server, and external service layers, and how they connect.

The diagram states the same split as a request path:
browser → React over HTTPS → NestJS over REST → Prisma → PostgreSQL, pooling connections rather than opening one per request. Fapshi and Google OAuth sit outside that backend boundary as their own External Services layer dependencies that LocalHands doesn't control, so they fail and rate-limit on their own schedule.
This split is a direct response to a specific set of non-functional requirements defined early in the project:

NFR	Target
Availability	99.9% uptime, minimal downtime
Performance	Fast page loads, responsive interaction even under concurrent load
Security	HTTPS/TLS on all communication; passwords and financial details hashed/encrypted at rest and in transit; protection against SQL injection and XSS
Scalability	Handle growing users, services, and transactions without performance degradation

Table 1: Non-functional requirements driving the architecture.

Engineering Decision: Splitting frontend and backend into separate repos means either layer can be redeployed, scaled, or swapped without touching the other.
Given fragmented connectivity and variable device quality across the target market, this isolation matters more than it would in a single-region SaaS product.

2. Tier 1-Frontend: React 19 + Vite

"dependencies": {
  "react": "^19.1.0",            // UI library
  "react-dom": "^19.1.0",        // DOM renderer for React
  "antd": "^5.26.1",             // component library (tables, forms, modals)
  "axios": "^1.10.0",            // HTTP client for the backend API
  "react-router-dom": "^7.6.2"   // client-side routing
},
"devDependencies": {
  "@tailwindcss/vite": "^4.3.0", // utility CSS, wired into the Vite build
  "vite": "^6.2.0"               // dev server + production bundler
}

A Single-Page Application: React 19, built with Vite, styled with Ant Design + Tailwind v4, deployed on Vercel. The full reasoning behind each tool choice-why React over alternatives, why Ant Design, why Vite-is its own post; what matters architecturally here is how the pieces fit together.

The app is routed by role, not just by path:

Category	Prefix	Auth Required	Layout
Public	`/`	No	`MainLayout` [Header + Footer]
Client	`/client/*`	Yes (CLIENT)	`ClientLayout` [Sidebar]
Provider	`/provider/*`	Yes (PROVIDER)	`ProviderLayout` [Sidebar]
Admin	`/admin/*`	Yes (ADMIN)	`AdminLayout` [Sidebar]

Table 2: Route prefixes, access rules, and layout per role

Auth state isn't passed manually on every request these two interceptors handle it once, globally:

// Axios interceptors (utils/api.ts)
request:  attach Authorization: Bearer <token> from localStorage  // every outgoing call is authenticated automatically
response: on 401 → clear token, show toast, redirect to /login    // session expiry handled in one place, not per-component

Engineering Decision: HashRouter over BrowserRouter was a deliberate trade it means client-side routing works correctly on static hosting (Vercel) without needing server-side rewrite rules.
SPA means one initial load, then only data, not full pages, moves over the wire afterward, which matters directly for users on a constrained connection.

3. Tier 2-API Layer: NestJS

The backend is a NestJS application sitting in front of PostgreSQL via Prisma, with Passport.js/JWT handling auth and class-validator/class-transformer handling DTO validation.
Swagger UI documents the API live at /api/docs. Why each of these over the alternatives is covered in the stack-and-tools post here, the focus is on what they let the architecture do.

Figure 2: Component hierarchy detailing child module communication with the root App

The backend runs 23 feature modules off a single root AppModule:
Grouped by domain, not left flat:

Domain	Modules
Infrastructure	`Config,` `Prisma,` `Common,` `Healthcheck`
Identity	`Auth,` `User,` `Provider,` `Client,` `Profile`
Marketplace	`Service,` `ServicePackage,` `ServiceAsset,` `ServiceOrder,` `Category`
Engagement	`Booking,` `Availability,` `Proposal,` `Review`
Money	`Contract,` `Payment`
Comms	`Messages,` `Notifications`
Platform	`Settings`

Table 3: The 23 feature modules, grouped by domain.

Every request follows the same pipeline before it reaches business logic:

Request
  → CORS                        // only whitelisted origins allowed
  → Compression                 // gzip the response body
  → Global ValidationPipe       // strip/reject/transform the payload
  → JwtAuthGuard (route-level)  // only runs on protected routes
  → Controller                  // receives the validated request
  → Service                     // business logic lives here
  → Prisma                      // typed query builder
  → PostgreSQL                  // data actually persists here

Figure 3: Request-pipeline

// main.ts-ValidationPipe config
{
  whitelist: true,            // strip unknown fields
  transform: true,            // cast payloads to DTO types
  forbidNonWhitelisted: true  // reject unexpected fields outright
}

Two flows worth detailing since they cross more than one module:

Flow	Steps
Provider verification	`verificationStatus` starts `PENDING` → Provider uploads ID doc via Profile module → Admin reviews manually → status set to `VERIFIED` or `REJECTED`. Only `VERIFIED` providers can submit Proposals-enforced server-side.
Authentication	`POST /api/auth/login` → `AuthService.validateUser()` → lookup by email/phone → `bcrypt.compare()` against stored hash → JWT signed (`email`, `phoneNumber`, `sub`, `name`, `role`, 1h expiry) → returned to client.

Table 4: Two flows that cross multiple modules.

What gets signed and carried on every request after:

// JWT payload structure
{
  "email": "user@example.com",   // one of two lookup fields on login
  "phoneNumber": "+237...",      // the other lookup field phone-first identity
  "sub": "<user id>",            // standard JWT subject claim
  "name": "...",                 // included so the UI can render it without a refetch
  "role": "CLIENT | PROVIDER | ADMIN",  // drives both UI routing and RoleGuard checks
  "exp": "<issued + 1h>"         // short-lived on purpose
}

Engineering Decision: Each module is internally isolated Payment logic doesn't reach into Contract internals, Review doesn't know how Proposals work. They aren't separate deployable services yet; that split is possible later precisely because NestJS enforces these boundaries now.

4. Tier 3-Data Layer: PostgreSQL + Prisma

Figure 4: How a query travels from the service layer down to the database.

Each box in the diagram is a real step a query takes, not just a simplified picture. A Service first calls PrismaService. PrismaService doesn't talk to PostgreSQL directly, it goes through @prisma/adapter-pg, an adapter that lets Prisma run its queries through the standard node-postgres library.
From there, the query goes into a connection pool: a small set of database connections that stay open and get reused, instead of opening a brand new connection for every single request.
That pooling matters most under load. Without it, a burst of requests at the same time would mean a burst of new database connections, and that's exactly the kind of thing that can quietly overwhelm a small Postgres instance.
The full database design, the User/Profile split, the ServiceOrder → Proposal → Contract lifecycle, the rule that blocks double payment was already covered in the previous post. A few extra tables from the full schema didn't make it into that article and are worth covering here:

Model	Role
`Availability`	Provider working hours per `dayOfWeek`; checked before a direct Booking
`ServicePackage`	Bundled Service offerings tied to a Provider
`ServiceAsset`	Media attached to a Service listing, typed via `AssetType`- the portfolio/visual-proof mechanism the field research called for
`Message`	`senderId` / `receiverId` pairs for in-app Client–Provider comms
`Notification`	Typed, per-user records (`message`, `type`, `read`) tied to events
`SystemSettings`	Platform config: maintenance mode, registration toggles, review auto-approval, currency, support email

Table 5: Supporting models not covered in the schema deep-dive post.



enum PaymentMethod {
  MTN_MOBILE_MONEY  // dominant rail, shipped first
  ORANGE_MONEY      // added once the escrow logic around the first rail was proven
  BANK_TRANSFER     // smaller share of volume, but real not assumed away
}

MTN MoMo and Orange Money both see active daily use in this market, and a smaller but real share of transactions still move via bank transfer. Encoding all three as first-class values rather than assuming one dominant rail keeps the schema honest about the payment landscape it actually serves.

Engineering Decision: The enum started narrow, a single, well-tested rail, and was widened to all three once the escrow logic around it was proven. Adding a PaymentMethod value is a migration, not a redesign, which is what made that expansion low-risk.

How the Payment module actually talks to Fapshi, the controller-to-gateway chain, and the mobile money handoff is worth its own walkthrough rather than a footnote here. That's coming in the Escrow Algorithm post.

5. Request Flow

1. User submits identifier + password           // Frontend
2. POST /api/auth/login                          // Frontend → API
3. AuthController → AuthService.validateUser()   // API
4. UserService looks up user by email/phone      // API → Prisma
5. bcrypt.compare(password, storedHash)          // API
6. Success → sign JWT, update lastLogin          // API → DB
   Failure → ForbiddenException → 401            // API → Frontend
7. Frontend stores token, redirects to dashboard // Frontend

The same pattern repeats for every other action on the platform-a Client posting a Service Order, a Provider submitting a Proposal, a Contract being accepted:

Frontend request → Controller validation → Service logic →
Prisma → PostgreSQL → Response → UI update
// same six-hop cycle regardless of which module handles the request

No full page reload, no server-rendered round trip-just a tight, predictable cycle through the same three layers every time.

6. Why This, Not Something Fancier

This is a conventional 3-tier system on purpose. No microservices, no event bus, no server-side rendering. The non-functional requirements driving it are concrete, not aspirational marketing language:

Commitment	Mechanism
Encrypted transport	HTTPS/TLS on every connection
Password safety	bcrypt hashing; never returned in API responses
Injection protection	Prisma parameterizes every query by construction
Failure visibility	Global exception filter + structured, sanitized logging (passwords/tokens redacted before write)
Horizontal scaling	Stateless backend modules can scale out, or split into services later, without a redesign

Table 6: Security and scalability commitments behind the architecture.

Given the real constraints, inconsistent connectivity, budget devices, a payment layer that has to work over mobile money, a well-bounded, boring architecture is what makes the harder problem (trust) solvable on top of it.

Next post:
Access control: how LocalHands distinguishes Clients, Providers and Admins, and how every request crossing this architecture gets authenticated and authorized.

Architecting Digital Trust: A Relational Deep Dive into the LocalHands Prisma Schema

Tiani pekins Ebika — Sat, 02 May 2026 21:10:12 +0000

Subtitle: How to model a secure, escrow-based marketplace for emerging economies using Prisma and PostgreSQL.
Schema.

In my previous article on Medium, I discussed the sociotechnical challenge of Information Poverty in the African gig economy. But as engineers, we know that solving social problems requires more than vision it requires a robust, type-safe, and scalable data architecture.
For LocalHands, I chose Prisma ORM with PostgreSQL. The goal was to build a "Technical Source of Truth" that could handle the complexity of service listings, competitive bidding (proposals), and secure escrow payments.
Below, I break down the core relational logic of the LocalHands schema

1. The Core Actor Model: User vs. Profile
In a marketplace, users often play multiple roles. However, security is paramount. I separated the User (authentication and roles) from the Profile (sensitive KYC data)

model User {
  id               Int              @id @default(autoincrement())
  role             UserRole         @default(CLIENT)
  phoneNumber      String           @unique
  email            String           @unique
  passwordHash     String
  profile          Profile?
  // ... relations to orders, contracts, and services
}

model Profile {
  id                 Int              @id @default(autoincrement())
  userId             Int              @unique
  user               User             @relation(fields: [userId], references: [id])
  verificationStatus VerificationStatus? @default(PENDING)
  nationalIdUrl      String?          // URL to encrypted storage
  mobileMoneyNumber  String?
}

Engineering Decision: By using a 1:1 relation for the Profile, we keep the User model lean for frequent authentication checks while isolating heavier metadata and verification documents.

2. Modeling the Bidding Lifecycle (Service -> Order -> Proposal)
Unlike standard e-commerce, a service marketplace is dynamic. A client doesn't just "buy"; they post a ServiceOrder, and providers reply with Proposals.

model ServiceOrder {
  id            Int              @id @default(autoincrement())
  serviceId     Int
  clientId      Int
  budget        Float?
  status        ServiceOrderStatus @default(PENDING)
  contract      Contract?          // Only exists once a proposal is accepted
}

model Proposal {
  id           Int          @id @default(autoincrement())
  providerId   Int
  serviceId    Int
  bidAmount    Float
  status       ProposalStatus @default(PENDING)
  contractId   Int?
}

Relational Integrity: Notice the optional contractId in the Proposal. This allows multiple providers to bid on one job, but ensures that only the accepted proposal transitions into a formal, binding Contract.

3. The Trust Engine: Contract and Escrow
This is where the code solves the Trust Gap. The Contract model acts as the central node for the entire transaction lifecycle.

model Contract {
  id            Int              @id @default(autoincrement())
  serviceOrderId Int              @unique
  escrowAmount  Float
  status        ContractStatus   @default(ACTIVE)
  payments      Payment[]
  reviews       Review[]
}

By enforcing a @unique constraint on the serviceOrderId, we prevent the "Double-Payment" bug. The contract is the only entity authorized to trigger a Payment release.

4. Localized FinTech Integration
To meet the reality of the Cameroonian market, the schema explicitly supports MTN Mobile Money and localized currency settings.

model Payment {
  id            Int             @id @default(autoincrement())
  contractId    Int
  amount        Float
  paymentMethod PaymentMethod   @default(MTN_MOBILE_MONEY)
  status        PaymentStatus   @default(PENDING)
}

model SystemSettings {
  currency           String   @default("XAF")
  currency_symbol    String   @default("FCFA")
  payment_gateway     String   @default("fapshi")
}

Why this matters: Hardcoding these enums and settings at the database level ensures that the business logic remains consistent and compliant with regional financial regulations.

Conclusion
This schema is designed to do more than just store data; it is designed to enforce trust. By leveraging Prisma's powerful relational features, I have built a foundation where Information Poverty is replaced by a transparent, verifiable history of service.
What’s Next?
Currently, I am architecting the system layers that will host this schema in production. In my next post, I'll break down the 3-Tier Architecture of LocalHands: the frontend (presentation), the NestJS API layer (application logic), and the PostgreSQL/Prisma data layer (persistence) and how this data model sits inside a scalable, resilient system designed for fragmented infrastructure.