2026 · ISTAD final project · Full stack, built solo

ChbasMun

A Khmer-first scam check for Cambodia

ChbasMun (ច្បាស់មុន, "be sure first") lets anyone check a phone number, bank account, KHQR code or link before sending money. People report scams, two different reviewers confirm them, and every identifier gets a risk level shown as a stamp in Khmer or English. Banks can ask the same question through a Partner API. I designed and built both sides: seven Spring Boot microservices behind a gateway, and the Next.js web app.

services + gateway
7 + 1
REST endpoints
100
lines of Java
19.5k
lines of tests
8.2k

01The problem

Why we built it

Scams in Cambodia move fast through Telegram, Facebook and fake loan pages, and victims usually only find out after paying. Warnings live in scattered chat groups, in Khmer, with no way to check a number in one place. And a public "scammer list" is dangerous: one false report can ruin an innocent shop. ChbasMun had to make checking easy, make reporting kind, and make sure no single person can mark a number as a scam.

02Frontend

Inside the UI

The main screens of the Next.js app and the components each one is built from. Pick a screen to see its layout and where its data comes from.

chbasmun.app/km/check
<SiteHeader />
<CheckForm />
<KhqrScanner />
<VerdictStamp />
<VerdictView />
<VerdictActions />

Paste anything or scan a KHQR code. The verdict shows a stamp, the reasons in plain words, what to do now, and buttons to watch, share or report.

Data

  • detectInput()
  • GET /risk/check
  • POST /risk/check-text

03How it's built

Follow one request

ChbasMun is a Next.js app in front of a gateway and seven Spring Boot services that talk through Kafka. Scroll to follow a check through every layer.

01 / 07 · The user

Someone checks a number before paying

On a phone, in Khmer by default. They paste a number or scan a KHQR code; the app detects the type in the browser before asking the server.

GET chbasmun.app/km/check?q=096 000 0555

Follow one request

Gateway + 7 Spring Boot services/api/v1

Zooming in on the API

One app, split by feature

chbasmun · gateway + 7 services8 modules · 1 PostgreSQL

  • Gateway
  • Identity
  • Reports & reviews
  • Risk scoring
  • Reputation & votes
  • Media
  • Notifications
  • Partner API
  1. Gradle build + tests
  2. Testcontainers
  3. Docker images
  4. Docker Compose

04Inside the system

Seven services, one platform

  1. 01 · The map

    One app, one door, seven services

    The web app talks to one gateway. Behind it, seven Spring Boot services each own one job and one database. They never read each other's tables: they call each other's APIs or react to each other's events on Kafka.

  2. 02 · Client

    The web app

    What people use: the check, the report wizard, reports, the account area and the review console. It renders on the server, keeps the access token on the server and calls the API through its own proxy.

    GET /api/backend/api/v1/risk/check → gateway
    • Tokens live in an encrypted cookie; the browser only sees name and roles.
    • Signed-in calls go through a same-origin proxy that adds the token and refuses cross-site writes.
    • Live notifications and evidence files have their own server routes for the same reason.
    • Sign-up goes straight from the browser, so rate limits count each visitor.
    • Next.js 16
    • React 19
    • NextAuth
    • TanStack Query
    • next-intl
  3. 03 · Edge

    Keycloak and the gateway

    Keycloak proves who you are; the gateway decides whether your request may pass and where it goes. Every service then checks the token again.

    GET /api/v1/reports → report-service
    • Rate limits: 30 checks a minute, 5 sign-ups an hour, 30 username checks a minute per address.
    • Banks get their own limit per partner, with usage metered per day.
    • Every error leaves in the same JSON shape with a trace id.
    • Spring Cloud Gateway
    • Redis
    • Resilience4j
    • Swagger UI for all services
  4. 04 · People & profiles

    identity-service

    Profiles, sign-up and verifier applications. Signing up creates the Keycloak user first and the profile second, and deletes the Keycloak user again if the profile fails, so the two never disagree.

    POST /api/v1/identity/register → 201
    Owns
    identity_db
    Publishes
    chbasmun.user · user.registered, user.profile_updated, verifier.approved
    • Clear sign-up errors: USERNAME_TAKEN, EMAIL_TAKEN, PASSWORD_POLICY.
    • Approving a verifier adds the role in Keycloak; the new token carries it.
    • Emails are never in events: other services ask an internal endpoint with a service token.
    • Spring Boot
    • Keycloak Admin API
    • JPA
    • Flyway
  5. 05 · Reports & reviews

    report-service

    Reports, comments, evidence links, the review workflow and content flags. A report needs two different reviewers to become confirmed, and nobody reviews their own report.

    POST /api/v1/reports/moderation/{id}/verdict
    Owns
    report_db
    Publishes
    chbasmun.report · report.submitted, report.verified, report.rejected, flag.created
    Reads
    chbasmun.user, chbasmun.reputation
    • Opening a report claims it for 15 minutes; a second reviewer is refused with CLAIMED_BY_OTHER.
    • Only one person's duplicates can be merged: different people's reports are different victims.
    • The public sees identifiers masked; reviewers see them in full.
    • At most 10 reports per person a day, with Retry-After.
    • Spring Boot
    • JPA
    • Optimistic locking
    • Outbox
  6. 06 · Scores every identifier

    risk-service

    Normalizes phone numbers, accounts, links and KHQR codes into one fingerprint, and scores each from 0 to 100: confirmed reports, distinct reporters, evidence, recency, votes weighted by reputation and bank disputes.

    GET /api/v1/risk/check?type=PHONE&value=096… → HIGH · 78
    Owns
    risk_db + Redis cache
    Publishes
    chbasmun.indicator · indicator.risk_changed, indicator.spike_detected, indicator.appeal_decided
    Reads
    chbasmun.report, chbasmun.reputation
    • Reasons are written out in Khmer and English, never "scammer" or "safe".
    • Owners can appeal; an upheld appeal stops older reports counting.
    • Official contacts (bank hotlines) are stamped OFFICIAL.
    • Five new reporters in 24 hours propose a scam alert, never send one.
    • Spring Boot
    • Scoring v2.2
    • Redis
    • KHQR parser
  7. 07 · Votes, points & badges

    reputation-service

    "This happened to me too" votes, a points ledger, tiers, badges and leaderboards. Careful reviewers and reporters of confirmed scams earn points; the leaderboards live in Redis and rebuild from the ledger.

    PUT /api/v1/reputation/reports/{id}/vote
    Owns
    reputation_db + Redis
    Publishes
    chbasmun.reputation · vote.cast, badge.awarded, tier.changed
    Reads
    chbasmun.report, chbasmun.user
    • No votes on your own report, and new accounts wait a day.
    • The vote summary says whether and when you can vote.
    • Empty leaderboards are rebuilt from the ledger at startup.
    • Spring Boot
    • Points ledger
    • Redis sorted sets
  8. 08 · Evidence files

    media-service

    Uploads of screenshots, voice messages and PDFs. It checks the real file type from the bytes, removes location data from photos and stores files in MinIO. Only the uploader and reviewers can open them.

    POST /api/v1/media → { kind: IMAGE }
    Owns
    media_db + MinIO
    Publishes
    chbasmun.media · media.uploaded
    • File type from the content, not the name.
    • EXIF and GPS data are stripped from every photo.
    • Files are streamed, never cached, never public.
    • Spring Boot
    • MinIO (S3)
    • Apache Tika
    • EXIF stripping
  9. 09 · Tells people what happened

    notification-service

    Turns events into in-app notifications pushed live over Server-Sent Events, and emails in the reader's language with retries and quiet hours. Also watch lists, moderated scam alerts and a weekly digest.

    GET /api/v1/notifications/stream (SSE)
    Owns
    notification_db
    Publishes
    chbasmun.notification · alert.sent
    Reads
    chbasmun.user, chbasmun.report, chbasmun.reputation, chbasmun.indicator
    Calls
    identity-service (contact), report-service (reviewer question)
    • Each event notifies a person at most once.
    • Scam alerts and the digest are opt-in; alerts are only sent after a moderator approves them.
    • Links point to the web app's pages in the reader's language.
    • Spring Boot
    • Server-Sent Events
    • Thymeleaf emails
    • Watch lists
  10. 10 · API for banks

    partner-service

    Banks and wallets look up payees in bulk, get signed webhooks when an identifier they asked about becomes risky, and send scam disputes from their customers, which enter normal review.

    POST /api/v1/partner/risk/lookups → items[]
    Owns
    partner_db
    Reads
    chbasmun.indicator, chbasmun.report
    Calls
    risk-service (batch lookups), report-service (disputes)
    • Partners send fingerprints of identifiers, never raw customer data.
    • Webhooks are signed (HMAC) and retried, with replay.
    • A suspended partner is refused at once.
    • Spring Boot
    • Client credentials
    • HMAC webhooks
    • Usage metering
  11. 11 · Events

    Kafka, with an outbox

    A service saves its change and an outbox row in the same transaction; a relay publishes the row to Kafka. So an event is never lost and never sent for a change that was rolled back. Every consumer records the events it handled, so a replay never counts twice, and failures land in dead-letter topics.

    INSERT outbox(...) → relay → chbasmun.report
  12. 12 · One report's journey

    From a report to a warning on your phone

    A second reviewer confirms → report-service publishes report.verified → risk-service raises the number to HIGH and publishes indicator.risk_changed → notification-service finds everyone watching that number → their phone shows the alert live, and banks that asked about it get a webhook.

    report.verified → indicator.risk_changed → WATCH_ALERT
  13. 13 · Operations

    Run it, watch it, trust it

    One docker compose starts everything: the services, Kafka, PostgreSQL, Redis, MinIO, Keycloak, Mailpit. Traces follow a request across HTTP and Kafka in Zipkin, metrics go to Prometheus and Grafana, and timeouts, retries and circuit breakers keep one slow service from taking the others down.

    make up · make logs s=risk-service · make dlt

05Features

What you can do on ChbasMun

  • Check before you pay

    Type or paste a phone number, bank account, link, Telegram or Facebook handle, or scan a KHQR code. The app detects what it is and returns a risk stamp with plain reasons.

  • Report a scam

    A five-step wizard with evidence uploads (photos are shrunk and stripped of location data), a privacy preview showing exactly what the public will see, and a saved draft.

  • Two-person review

    A report only counts as confirmed when two different reviewers agree. Nobody reviews their own report, and a 15-minute claim stops two reviewers deciding at once.

  • Risk score

    Each identifier gets a 0-100 score from confirmed reports, distinct reporters, evidence, recency and bank disputes, with the reasons written out in Khmer and English.

  • Appeals

    The owner of a wrongly reported number can appeal with evidence; a moderator can clear it so older reports stop counting.

  • Watch lists & live alerts

    Watch up to 50 identifiers and get a live notification when one's risk goes up, in the app over Server-Sent Events and by email.

  • Community

    "This happened to me too" votes, comments, reputation, tiers, badges and a leaderboard per province.

  • Review console

    A two-pane desk for reviewers with an evidence viewer, keyboard shortcuts, merges, and moderation of appeals, flagged content, scam alerts and verifier applications.

  • Partner API

    Banks look up identifiers in bulk with client credentials, receive signed webhooks and send scam disputes from their own customers.

  • Khmer first

    Khmer is the default language, counts and dates use Khmer digits, and share images render Khmer text correctly.

06Tech stack

What it's built with

Frontend

  • Next.js 16 (App Router)
  • React 19
  • TypeScript
  • Tailwind CSS v4
  • shadcn/ui + Radix
  • NextAuth (Keycloak)
  • TanStack Query
  • openapi-fetch + generated types
  • next-intl (KM / EN)
  • zxing-wasm (KHQR)
  • HarfBuzz (Khmer share images)
  • Vitest + Testing Library

Services

  • Java 21
  • Spring Boot
  • Spring Cloud Gateway
  • Spring Security (OAuth2 resource server)
  • Spring Data JPA
  • Flyway
  • Resilience4j
  • Thymeleaf emails
  • springdoc OpenAPI

Events & data

  • Apache Kafka (outbox, 7 topics)
  • PostgreSQL (a database per service)
  • Redis (cache, rate limits, leaderboards)
  • MinIO (evidence files)

Identity & ops

  • Keycloak (OIDC, roles, password policy)
  • Docker Compose
  • Testcontainers
  • Prometheus + Grafana
  • Zipkin tracing
  • Mailpit

07Under the hood

How a few parts work

From a report to a risk level

  1. 1report-service saves the report and an outbox row in the same transaction, so an event is never lost or sent for a report that was not saved.
  2. 2The outbox relay publishes report.submitted to Kafka. risk-service, reputation-service and notification-service each consume it once, tracked in their own processed-events table.
  3. 3When the second, different reviewer confirms, report.verified goes out and risk-service recalculates the identifier's score and level.
  4. 4If the level goes up, everyone watching that identifier gets a live notification, and five new reporters in 24 hours propose a scam alert that a moderator must approve before anything is sent.

Two different reviewers, never one

  1. 1Opening a report claims it for 15 minutes; another reviewer trying to open it is told someone else is reviewing it.
  2. 2The first confirmation only moves the report to a second review. The same person cannot give the second opinion, and nobody can review their own report.
  3. 3Rejecting needs a reason and a kind note for the reporter, and a rejection after a first confirmation is recorded as a disagreement.
  4. 4Confirmed and rejected decisions feed the reviewers' reputation, so careful reviewing is rewarded.

Keeping tokens away from the browser

  1. 1NextAuth signs people in with Keycloak (authorization code with PKCE). The access and refresh tokens stay in an encrypted cookie; the browser only sees the name and roles.
  2. 2Signed-in calls go through a same-origin proxy in Next.js that adds the bearer token on the server and refuses cross-site writes.
  3. 3Evidence images and the live notification stream go through their own route handlers, which check the role and stream the response with the token added server-side.
  4. 4Sign-up is the exception: it is sent straight from the browser, so the gateway's per-address limit counts each visitor, not the web server.

Khmer that renders correctly

  1. 1Counts, dates and steps in Khmer text use Khmer digits (០-៩), while phone numbers, accounts and amounts keep Latin digits. Browsers' Intl cannot do this reliably, so digits are converted by hand on both server and client.
  2. 2Social share images are made on the server, where the image library cannot shape Khmer script, so Khmer text is shaped with HarfBuzz into SVG paths first.
  3. 3Messages are checked by a test: same keys and placeholders in both languages, no plural forms in Khmer, and never the word "safe" for a number.

08Build log

Everything we did, in order

16 steps and about 182 commits across the two repositories. Each step was its own branch, merged only when the build, the tests and the lint passed. Open a step to see what it added.

  1. 01BackendFoundation16 commitsA Gradle multi-module repository with a shared library, a skeleton for every service, the gateway and Docker Compose.
    • Shared event envelope, error format and correlation ids
    • Every service starts, answers /ping and is routed by the gateway
    • CI build with a secret scan, README and architecture decision records
  2. 02BackendLogin and identity9 commitsKeycloak with an imported realm, JWT checks in the gateway and every service, and identity-service.
    • Profiles, sign-up through the Keycloak admin API with rollback
    • Verifier applications that add the role in Keycloak
    • Security and business-rule tests
  3. 03BackendReports and evidence10 commitsThe report model, the API and evidence uploads, with the identifier normalizer shared by every service.
    • Normalizer, extractor and KHQR parser in the shared library
    • Uploads checked by content, location data stripped
    • Report events published after commit
  4. 04BackendRisk scoring11 commitsrisk-service consumes report events, scores each identifier and serves the public check.
    • Idempotent Kafka consumers and dead-letter topics
    • Risk scorer v1, trending and the official list
    • Fail fast with 503 when a service is down
  5. 05BackendReview, votes and appeals9 commitsThe two-reviewer workflow, community votes and owner appeals, with scoring v2 using all of them.
    • Claims, verdicts, merges and the moderation queue
    • Votes with a read model in reputation-service
    • Appeals and scoring v2
  6. 06BackendReputation10 commitsPoints, tiers, badges and leaderboards, and votes weighted by the voter's reputation.
    • Points ledger and tiers
    • Badges and province leaderboards in Redis
    • Scoring v2.1 with reputation-weighted votes
  7. 07BackendNotifications12 commitsnotification-service: in-app notifications over SSE, emails, watch lists, scam alerts and a weekly digest.
    • Contact lookups with a service token, never emails in events
    • Emails with templates, retries and quiet hours
    • Moderated scam alerts from spike detection
  8. 08BackendPartner API15 commitspartner-service for banks: bulk lookups, signed webhooks and scam disputes, with a fake bank to test against.
    • Partner clients created in Keycloak
    • Hashed lookups that auto-watch, HMAC webhooks with retries
    • Scoring v2.2 with bank disputes, per-partner rate limits
  9. 09BackendHardening7 commitsMaking it dependable: every event through an outbox, tracing, metrics and resilience.
    • Transactional outbox and relay for all events
    • Distributed tracing over HTTP and Kafka with Zipkin
    • Timeouts, retries, circuit breakers and faster startup
  10. 10Web appSkeleton16 commitsThe Next.js app: design tokens, the verdict stamp, Khmer and English routing, Keycloak login and a typed API client.
    • A stamp component for verdicts
    • Types generated from the gateway's OpenAPI documents
    • Khmer by default, whatever the browser's language
  11. 11Web appThe check11 commitsThe main page: detect what was typed, scan KHQR codes, show the verdict, profiles with history, share links.
    • Detection of phones, accounts, links, Telegram and Facebook
    • KHQR scanning with the camera or a screenshot
    • Share images with correctly shaped Khmer text
  12. 12BackendSupport for the web app21 commitsThree rounds of backend changes the frontend needed, plus sign-up with clear errors.
    • Rate limits per address, vote counts, Retry-After, vote eligibility
    • Content flags, Khmer digits in every service, links in the reader's language
    • Sign-up codes and a public username check
  13. 13Web appReporting13 commitsThe report wizard, evidence uploads, the feed, report pages with votes and comments, and the reporter's own actions.
    • Five steps with a saved draft and a privacy preview
    • Khmer digits written by hand (browsers can't)
    • Server-side token refresh for long sessions
  14. 14Web appThe account area11 commitsLive notifications, the dashboard, settings, watch lists, the verifier application, leaderboards and content flags.
    • A server route that streams notifications with the token added
    • Settings that save at once and roll back on failure
    • Votes that follow the server's eligibility
  15. 15Web appThe review console8 commitsEverything reviewers and moderators need, from the queue to admin tools.
    • Claims with a timer, verdicts that restate their consequence, keyboard shortcuts
    • Evidence through a role-checked proxy
    • Appeals, flags, scam alerts, applications, partners and stats
  16. 16Web appSign up3 commitsCreating an account in the app, then signing in through Keycloak with only the password left to type.
    • A live username check that waits for typing to pause
    • Errors on the right field, rules that match the login server
    • Forgot password and terms and privacy pages

Problems that took real work

ProblemBrowsers can't write Khmer digits: Chrome's number formatting has no Khmer numerals, and pages flipped back to Latin digits after loading.

FixDigits are converted by hand with one helper used by the server and the browser, and only for counts and dates, never phone numbers or amounts.

ProblemShare images showed broken Khmer: the image library can't shape Khmer script.

FixKhmer text is shaped with HarfBuzz into SVG paths on the server before the image is drawn.

ProblemAn event could be lost if a service crashed between saving and publishing.

FixA transactional outbox: the change and the event are saved together, and a relay publishes afterwards. Consumers ignore events they already handled.

ProblemTwo reviewers could decide the same report at once.

FixA 15-minute claim per report, optimistic locking on the report row, and a clear "someone else is reviewing this" message.

ProblemAfter 15 minutes, server-rendered pages lost the session: the access token had expired.

FixThe server refreshes an expired token for each request, so pages and the proxy keep working while the browser updates its session.

ProblemLeaderboards disappeared when Redis restarted.

FixRedis now keeps an append-only file, and reputation-service rebuilds empty boards from the points ledger when it starts.

09Shipping

From commit to production

  1. 01Every service, Kafka, PostgreSQL, Redis, MinIO, Keycloak, Mailpit and the observability stack start with one docker compose command.
  2. 02Each service builds and runs its tests with Gradle; integration tests use Testcontainers with the same images as production.
  3. 03Flyway applies each service's own migrations when it starts, and the realm settings are applied to a running Keycloak by a script, without a reset.
  4. 04The web app's API types are generated from the gateway's OpenAPI documents, so a backend change shows up as a type error in the frontend.
  5. 05The Next.js app builds as a standalone server for its own Docker image.

10My role

What I built

ChbasMun is my own project from end to end: I designed the system, wrote both repositories and tested them, step by step from the first service to the review console.

  1. 01

    The microservices

    Seven Spring Boot services and a gateway, each with its own database, Flyway migrations and tests, talking through a transactional outbox and Kafka.

  2. 02

    Trust & safety rules

    The two-reviewer rule, claims, appeals, content flags, moderator-approved scam alerts and a risk score whose reasons can be read in plain Khmer.

  3. 03

    The web app

    A Khmer-first Next.js app: the check, the report wizard, live notifications, the account area, the review console and sign-up, all working on 320 px phones.

  4. 04

    Security

    Keycloak with PKCE, tokens kept on the server, role checks in the gateway, every service and every page, rate limits per address, and evidence served only to reviewers.

  5. 05

    Partner API

    Bulk lookups for banks with client credentials, signed webhooks with retries, and scam disputes that feed the risk score.

  6. 06

    Quality

    Integration tests on real PostgreSQL, Kafka and Redis with Testcontainers, frontend tests with Vitest, and accessibility and Lighthouse checks on the main pages.

ChbasMun was built by me alone as my ISTAD final project, in two repositories: ChbasMun-Backend (the services) and ChbasMun-UI (the web app). The web app's API types are generated from the services' OpenAPI documents, so both sides stay in step.