DEV Community: Tiani Pekins Ebika

JWT Authentication and Role-Based Access Control in LocalHands

Tiani Pekins Ebika — Mon, 21 Sep 2026 20:56:48 +0000

Subtitle: How every request crossing the LocalHands API gets authenticated and role-checked before it touches any business logic.

1. The Problem This Solves
LocalHands has three user roles - CLIENT, PROVIDER, and ADMIN - each with a different set of permitted actions. A Client can post a Service Order. A Provider submits Proposals. An Admin manages verification. None of those actions should cross role boundaries, and no action should be possible without a verified identity behind it.
This article walks through exactly how that enforcement is implemented, end to end, using the real code from the LocalHands backend.

2. The Login DTO - What the API Accepts
Every login request is validated against a typed DTO before it reaches any business logic:

// src/auth/dto/login.dto.ts
export class LoginDto {
  @IsString()
  @IsNotEmpty()
  identifier!: string; // accepts email OR phone number

  @IsString()
  @IsNotEmpty({ message: 'Password is required' })
  @Length(8, 100, { message: 'Password must be at least 8 characters long' })
  password!: string;
}

The identifier field is the first concrete HCI decision in the auth layer: it accepts either an email address or a phone number. In a market where phone numbers are tied to MTN MoMo and Orange Money accounts and often serve as primary identity, forcing email-only login would exclude a meaningful share of users before they even get past the login screen.

3. The Authentication Flow - AuthService

// src/auth/auth.service.ts (validateUser)
async validateUser(
  identifier: string,
  password: string,
): Promise<Omit<User, 'passwordHash'> | null> {
  let user: User;
  try {
    if (identifier.includes('@')) {
      user = await this.usersService.findByEmail(identifier);
    } else {
      user = await this.usersService.findByPhoneNumber(identifier);
    }
  } catch (error) {
    return null;
  }

  if (user && (await bcrypt.compare(password, user.passwordHash))) {
    const { passwordHash: _, ...result } = user;
    return result;
  }
  return null;
}

Three things worth naming here:
Identifier routing - identifier.includes('@') routes the lookup to email or phone number. Simple, effective, and requires no additional field from the user.
bcrypt.compare() - passwords are never stored in plaintext. The stored value is a hash; bcrypt.compare() checks the submitted password against it without ever reconstructing the original.
passwordHash is stripped before return: - const { passwordHash: _, ...result } = user means the hash never travels beyond this function.
It does not appear in the JWT payload, it does not appear in the response body, it does not leave the auth layer.

// src/auth/auth.service.ts (login)
async login(loginDto: LoginDto) {
  const validatedUser = await this.validateUser(identifier, password);
  if (!validatedUser) {
    throw new ForbiddenException('Invalid credentials');
  }
  await this.usersService.updateLastLogin(validatedUser.id);

  const payload = {
    email: validatedUser.email,
    phoneNumber: validatedUser.phoneNumber,
    sub: validatedUser.id,
    name: validatedUser.name,
    role: validatedUser.role,
  };

  return {
    access_token: this.jwtService.sign(payload),
    user: validatedUser,
  };
}

updateLastLogin() fires on every successful login, a timestamped audit trail built into the authentication flow rather than fixed on later.
The JWT payload carries exactly five fields:email, phoneNumber, sub (the user's ID), name, and role.
The role field is what every downstream guard reads to make authorization decisions.

4. The JWT Strategy - Token Validation

// src/auth/jwt.strategy.ts
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(config: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: config.get<string>('JWT_SECRET'),
    });
  }

  validate(payload: JwtPayload) {
    return {
      id: payload.sub,
      email: payload.email,
      name: payload.name,
      role: payload.role,
      phoneNumber: payload.phoneNumber,
    };
  }
}

ignoreExpiration: false means an expired token is rejected outright - no grace period, no silent acceptance. ExtractJwt.fromAuthHeaderAsBearerToken() means the token must travel in the Authorization header as a Bearer token, not in a cookie or query string.
The validate() method's return value is what gets attached to request.user, the object that every controller and guard downstream reads when it needs to know who is making the request.

5. The Guards - JwtAuthGuard and RoleGuard

// src/auth/guards/jwt-auth.guard.ts
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}

// src/auth/guards/role.guard.ts
@Injectable()
export class RoleGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.get<string[]>(
      'roles',
      context.getHandler(),
    );
    if (!requiredRoles) {
      return true; // no roles required - allow through
    }
    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.includes(user.role);
  }
}

JwtAuthGuard is a single-line extension of Passport's AuthGuard('jwt').
It delegates all token validation to the JWT strategy and blocks the request with a 401 if validation fails.
RoleGuard reads the metadata set by a @Roles() decorator on the route handler, pulls user.role from the request object that JwtAuthGuard already populated, and checks whether the user's role is in the required list.
If no roles are required on a route,RoleGuard passes the request through without checking.
The guard order matters:

flowchart LR
    A["📤 Request<br/>Authorization: Bearer &lt;token&gt;"] --> B["🔒 JwtAuthGuard"]
    B --> C["JwtStrategy.validate()"]
    C --> D["Attach user to<br/>Request object"]
    D --> E["🎮 Controller<br/>accesses req.user"]

    style B fill:#e1f5fe
    style D fill:#c8e6c9

JwtAuthGuard always runs first because RoleGuard reads request. user- an object that only exists after JwtAuthGuard has validated the token and called JwtStrategy.validate(). If the order were reversed, RoleGuard would try to read a user object that does not exist yet.

6. Guards in Action - The Proposal Controller

// src/proposal/proposal.controller.ts
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
@Post()
@HttpCode(HttpStatus.CREATED)
@ApiOperation({ summary: 'Create a new proposal' })
create(@Body() createProposalDto: CreateProposalDto) {
  return this.proposalService.create(createProposalDto);
}

Every protected route in the Proposal controller carries @UseGuards(JwtAuthGuard) and @ApiBearerAuth(). The @ApiBearerAuth() decorator is what tells Swagger UI to show the padlock icon and the token input field at /api/docs - it does not enforce anything at runtime, but it makes the auth requirement visible to anyone testing the API.
@HttpCode(HttpStatus.CREATED) sets the success response to 201. The @ApiResponsedecorators document the possible error states: 401 for a missing/invalid token, 404 for a service or provider that does not exist. These are not just documentation - they map to real exceptions thrown inside the service layer.

7. The Full Request Pipeline
Putting it together, here is what every authenticated request travels through:

POST /proposal (with Authorization: Bearer <token>)

→ Global ValidationPipe
    whitelist: true              // strips unknown fields from body
    transform: true              // casts body to CreateProposalDto
    forbidNonWhitelisted: true   // rejects unexpected fields

→ JwtAuthGuard
    ExtractJwt.fromAuthHeaderAsBearerToken()
    ignoreExpiration: false
    JwtStrategy.validate() → attaches user to request

→ RoleGuard (if @Roles() decorator present on handler)
    reads request.user.role
    checks against required roles

→ ProposalController.create()
    receives validated DTO + authenticated user

→ ProposalService.create()
    business logic + Prisma query

→ PostgreSQL

Without clearing, nothing reaches ProposalController without clearing JwtAuthGuard. Nothing reaches ProposalService without clearing the controller's DTO validation. The pipeline is linear; each layer depends on the one above it passing cleanly.

💡 For a full breakdown of the system architecture and tech stack decisions behind LocalHands, check out my article on Medium.

What's Next
With authentication and authorization in place, the next article covers the entire trust model, which centers on the Escrow Architecture. Learn how LocalHands programmatically locks a Client's payment at contract formation, securely holds it through the work period, and triggers the release to the Provider based on verified completion protocols.

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.