WeTrainEducation & Tech

WeTrainEducation & Tech is a full-scale digital services platform combining professional training, enterprise software solutions, marketing services, customer management, payments, order processing, certifications, project inquiries, and admin operations within one connected ecosystem.

One Supabase identity, four business systems, one deployable Next.js application. A public marketing site plus three internal products (Education, CRM, HRM) and an internal Store, built so that each business area can change without putting the others at risk.

WeTrainEducation & Tech sells training courses, software and marketing services, and runs an internal organisation around that. In practice that means four very different groups of people use the same company's systems:

Off-the-shelf tools covered each need badly and none of them shared an identity. The brief was to replace the patchwork with one coherent platform, without building four separate apps that would each need their own login, deploy and on-call.

Constraints that shaped every decision

• Small team, one deployable. Operational overhead had to stay close to zero: no service mesh, no per-module infrastructure.
• Real money and real people's data. Payments, payroll-adjacent scoring and applicant CVs mean a wrong permission is an incident, not a bug.
• Live data. Schema changes must be backward compatible and rehearsed on a test database first.
• Bangladesh context. Local payment gateway (SMS Pay BD), Asia/Dhaka time for all scheduled work, Bangla as a first-class language on the public site.
• AI-assisted development. The repo is worked on with coding agents, so the architecture needs to be legible: explicit boundaries, written rules, and fast feedback.

A modular monolith: one Next.js application with hard internal boundaries, one Supabase project as the single source of identity and data, and a layered authorization model that fails closed.

3.1 Context and containers

3.2 Module ownership

Every route belongs to exactly one module. Shared code is deliberately small, and a module never imports another module's business logic.

3.3 Dependency direction

The arrows only ever point down into the shared kernel. CRM links to a customer by profile_id, never by importing Education code. This is what lets an engineer, or an AI agent, work on HRM payroll-adjacent logic with confidence that Education checkout cannot break.

Each decision below is recorded as a short ADR: context, decision, alternatives and the cost we accepted. The longer-form originals live in docs/.

ADR-001: Modular monolith, not microservices or a Turborepo

• Context: Four systems with different owners and release pressure, but a team small enough that distributed systems would dominate the work.
• Decision: One Next.js app. Boundaries are enforced by route prefixes, per-module folders (_actions, _components, _lib, _constants) and written rules, not by network hops.
• Rejected: Microservices (operational cost, cross-service auth); Turborepo with one app per module (four deploys, duplicated shell and auth, no real isolation gain at this size).
• Cost: Boundaries are social plus lint-level, not physical. Mitigated by the "Module boundaries" skill file and by keeping shared code minimal.
• Exit path: Each module already has its own route group, tables and guards, so it can be lifted into its own app if scale ever demands it.

ADR-002: One identity (auth.users), separate domain profiles per module

This is the load-bearing decision of the whole system.

• Context: The same person can be a student, a sales marketer, an employee and a store user at the same time.
• Decision: auth.users is the only identity. Each module owns a table whose primary key is the auth user id: profiles, crm_users, hrm_users, store_users. Having a row = having access to that module.
• Rejected: (A) one fat users table with ~20 mostly-null columns and a shared RLS policy; (B) separate auth per system (no SSO, email collisions, three bills).
• Why it works: Roles live in separate namespaces (MARKETER never collides with EMPLOYEE), each table gets its own indexes and RLS, and a bug in one module's schema cannot corrupt another's.
• Cost: Email is denormalised in several places, so a database trigger keeps it in sync; role resolution touches several tables (mitigated in ADR-004).

Identity: every module table shares the primary key of auth.users.

Education and CRM: customer money flow and the sales pipeline.

HRM and Store: weekly reporting, recruitment, and the ledger-backed shop.

ADR-003: Priority-based routing across modules

A user with several memberships needs a deterministic home. The rule is Education > CRM > HRM > Store, with an explicit module switcher (see the product tour) for everything else.

The same priority table exists in two places on purpose: proxy.ts for fast redirects and app/dashboard/page.tsx for the server-rendered entry. The written rule in AGENTS.md and docs/CRITICAL_SYSTEMS.md keeps them aligned; a shared, tested routing function is on the roadmap.

ADR-004: One role resolver, getCurrentUserWithRoles()

• Context: Layouts, guards, the sidebar and the module switcher all need to know "what can this user do?". Ad-hoc lookups scatter authorization logic and multiply database round-trips.
• Decision: A single server function returns a typed UserWithRoles (education role, CRM role, HRM role, Store role + granular Store permissions, derived capability flags). Guards (requireCrmAdmin(), requireHrmSuperAdmin(), requireStorePermission(...)) are thin wrappers over it.
• Detail: Missing optional tables (a module not yet rolled out) degrade to "no access" instead of crashing; a deactivated HRM user resolves to no HRM access (activeHrmRole).
• Cost: It is a hot path: five indexed point lookups per call, currently issued sequentially. Accepted for correctness; running them concurrently and memoising per request are on the roadmap.

// app/utils/auth/require.ts (excerpt): every guard is the same two steps
export async function requireCrmAdmin(): Promise<UserWithRoles> {
  const roles = await requireAuth(); // 1. signed in + has any module
  if (!isCrmAdmin(roles)) redirect("/unauthorized"); // 2. has this specific capability
  return roles;
}

ADR-005: Authorization is layered, and the proxy is deliberately not the security boundary

Next.js 16 renamed middleware to proxy and its own documentation steers authors away from doing heavy authorization there. We follow that guidance:

• proxy.ts does only what must happen on every request: refresh the Supabase cookie, redirect anonymous users, send logged-in users to the right app home.
• Real enforcement happens in server layouts and server actions (requireXAccess()), and finally in Postgres RLS.
• The proxy fails closed: if the role lookup throws on a protected route the user is sent to /login, never waved through. Public routes are never blocked by an infrastructure blip.

See Section 6 for the full picture.

ADR-006: Server Actions for mutations, Route Handlers only for machines

• Decision: Human-driven writes go through Server Actions colocated under app/**/_actions/. Route Handlers are reserved for things a browser form cannot do: webhooks, cron, signed downloads, uploads.
• Why: Actions give end-to-end types, no hand-written API surface to secure, and revalidatePath for cache coherence.
• Rule: A "use server" file may only export async functions, so constants and enums live in sibling _constants/ modules.

ADR-007: Three Supabase client flavours, with the privileged one opt-in

The admin client is server-only, documented as dangerous at its definition, and every call site is expected to sit behind a requireXAdmin() guard. Env access is centralised in env.ts, which also accepts both the new (publishable / secret) and legacy (anon / service_role) Supabase key names so the app survives the platform's key migration.

ADR-008: Database-first safety (RLS, forward-only migrations, test then live)

• RLS on, always. Every new table is evaluated for RLS immediately; policies are tested for the intended role and one unintended role.
• Forward-only, additive migrations. Applied migration files are never edited. Because production holds live data, changes are backward compatible.
• Two-step rollout. npm run migrate:test, verify behaviour and RLS, then npm run migrate:live. The migration script knows both project refs and refuses to guess.
• Narrow public writes. The public proposal form inserts with the anon key under a policy that only permits a fresh NEW row and forbids setting any lifecycle field, so a visitor can create but never read, update or escalate:

CREATE POLICY "proposals_public_insert" ON public.proposals
  FOR INSERT TO anon, authenticated
  WITH CHECK (
    status = 'NEW'
    AND lead_id IS NULL
    AND reviewed_by IS NULL
    AND reviewed_at IS NULL
    AND internal_note IS NULL
  );

ADR-009: Idempotent, secret-protected scheduled work

Every cron endpoint (/api/hrm/cron/*, /api/billing/cron/run) is protected by a shared secret (X-CRON-SECRET or Vercel's bearer token) and is safe to run twice. Weeks are created atomically and de-duplicated; invoices are de-duplicated on (schedule_id, due_on); reminders and warnings are recorded so a retried run sends nothing new. See Section 9.

ADR-010: Payments through a signed, verified webhook

Order fulfilment is driven only by an HMAC-SHA256-verified webhook from SMS Pay, compared with crypto.timingSafeEqual over the raw request body. The browser redirect is never trusted as proof of payment, and the /api/checkout/confirm route is a read-only status check that exists purely so the checkout page can show progress. The subscription system adds a second, separate webhook endpoint (mapping inv_<id> back to an invoice through a unique payment-link intent id) so the original checkout path stayed untouched while billing was added.

ADR-011: Subscriptions as scheduled payment links, not card-on-file

The local gateway has no auto-debit. Rather than fake it, billing is a daily idempotent cycle that materialises invoices, issues a 14-day payment link, emails it, reminds at +3 and +7 days, and marks overdue. It is simple, auditable, and does not require storing payment credentials.

ADR-012: Cookie-based i18n with no URL segment

Locale (bn / en) is stored in a NEXT_LOCALE cookie and resolved server-side by next-intl. English is the default; Bangla is one click away. This avoided restructuring every route under /[locale] and keeps auth callback URLs stable. Only the public site is translated today; dashboards remain English by design (the staff working language).

ADR-013: Docs as part of the architecture

AGENTS.md is the single source of truth for contributors and AI agents, with a required reading order (CRITICAL_SYSTEMS → skills → module docs → stack docs → code) and an explicit list of high-risk areas (proxy.ts, app/utils/auth/*, app/utils/supabase/*, app/auth/*, cron routes, payment flows). docs/ is kept as a durable reference set, not a task log.

Decision summary

5.1 The role resolver

The returned object is deliberately flat and boring:

interface UserWithRoles {
  userId: string;
  email: string;
  profileRole: "customer" | "admin" | null;
  crmRole: "ADMIN" | "MARKETER" | null;
  hrmRole: "SUPER_ADMIN" | "ADMIN" | "EMPLOYEE" | null;
  storeRole: "USER" | "ADMIN" | null;
  hasEducationAccess: boolean;
  hasCrmAccess: boolean;
  hasHrmAccess: boolean;
  hasStoreAccess: boolean;
  storePermissions: StorePermission[]; // owner_purchase_manage, balance_add, ...
  storeCapabilities: StoreCapabilities; // role AND permission, pre-computed
  canAccessCrmAdmin: boolean;
  canActAsCrmMarketer: boolean;
}

5.2 Role matrix

* Store admins hold granular permissions (stock_manage, product_manage, invoice_manage, balance_add, owner_purchase_manage, permissions_manage). Being ADMIN is necessary but not sufficient.

6.1 The path of a protected request

6.2 What each layer is responsible for

6.3 A worked example: signed document downloads

CRM contracts live in a private Storage bucket. The download route resolves the caller, loads the document with the privileged client, then applies application-level policy that mirrors RLS: any CRM user, or the specific customer the current version was explicitly shared with. It returns a 5-minute signed URL, never a public link.

// app/api/documents/[id]/download/route.ts (excerpt)
const isCrm = roles.hasCrmAccess;
const isSharedCustomer =
  doc.customer_profile_id === roles.userId &&
  doc.shared_at !== null &&
  doc.is_current;

if (!isCrm && !isSharedCustomer) {
  return NextResponse.json({ error: "Forbidden" }, { status: 403 });
}

const { data: signed } = await supabase.storage
  .from(doc.storage_bucket || "crm-documents")
  .createSignedUrl(doc.storage_path, 60 * 5, { download: doc.file_name });

7.1 Principles

7.2 The CRM sales pipeline

Every transition writes a row to deal_events (STAGE_CHANGED, NOTE, VALUE_CHANGED, OWNER_CHANGED, WON, LOST, REOPENED), so the timeline on the deal page is a read of an immutable log rather than a derived guess.

7.3 The internship pipeline

Applicants have no direct table access. The public form writes through a server action using the service role, protected by a unique (program, email) index and a best-effort rate limiter. Applicants follow progress with an unguessable tracking token, and internal stages that should stay private (waitlist, no-show, declined offer) are collapsed before they reach the applicant-facing view.

// lib/internships/status.ts (excerpt): 13 internal states become 7 applicant-facing stages
export function toApplicantStage(status: string): ApplicantStage {
  switch (status) {
    case "SUBMITTED":
      return "received";
    case "UNDER_REVIEW":
    case "WAITLISTED":
      return "review"; // a waitlist is never revealed
    case "INTERVIEW_SCHEDULED":
    case "INTERVIEWED":
      return "interview";
    case "SELECTED":
    case "OFFER_ACCEPTED":
      return "selected";
    /* ... */
    default:
      return "closed"; // rejected, declined, no-show, ...
  }
}

7.4 Database change management

All 104 migrations apply cleanly on a fresh local Supabase stack (supabase start), which is also how the screenshots in this document were produced.

8.1 Landing: public conversion

• Server-rendered marketing pages (home, services, courses, software, marketing, pricing, internships, certificates, employees, legal pages).
• A 4-step proposal wizard (React Hook Form + Zod) that inserts a proposal with the anon key under the narrow RLS policy above.
• Internship application with CV upload, applicant tracking page (/internships/track/[token]), offer accept/decline (/internships/offer/[token]) and public certificate verification (/verify/intern/[code]).
• English by default with a Bangla switch; a floating chat/WhatsApp entry point; dark, yellow-branded design.

8.2 Education: customers and payments

• Customers browse packages, buy through SMS Pay, and see payments, subscriptions and the documents shared with them.
• Checkout creates a payment intent, then waits for the verified webhook (FINAL_STATUSES: completed, rejected, expired) before moving the order.
• The education admin dashboard summarises customers, revenue, orders and pending payments.

8.3 CRM: from lead to recurring revenue

Design notes worth calling out:

• Leads are written through the service-role client behind CRM guards because the lead RLS model is built around that write path; deals use the authenticated client, so RLS applies. The difference is intentional and documented per action file.
• Contracts are not a separate table: a contract is a document with a kind and nullable contract_status, effective_date, expires_date, counterparty. Fewer joins, one upload path, one RLS policy.
• Nothing is customer-visible until a CRM user shares it.

8.4 HRM: performance, recruitment and attendance

Three sub-systems share the module:

1. Weekly reporting and scoring. Employees submit weekly task reports; admins mark them with a single 0–100 score; a Friday cron closes the week and computes results; a super admin generates the monthly average and tiers (BONUS, APPRECIATION, IMPROVEMENT, FINE). All time logic is pinned to Asia/Dhaka, and week keys are validated to be the Friday date by a database CHECK constraint.
2. Internship recruitment. Programs, positions, applications, scored reviews, scheduled interviews (with .ics invites and reminder emails), offers with expiry, and onboarding.
3. Intern attendance and certification. Mandatory/optional shifts, grace and minimum-presence rules, no-show handling, attendance warnings, completion, certificate issuance and revocation.

8.5 Store: a tiny ledger-backed shop

• Employees buy snacks and stationery on account; balances are derived from a ledger, not stored.
• Admins manage products, stock movements, month closures and owner purchases, gated by granular permissions.
• Reports export to CSV and PDF (jspdf, xlsx).
• Independence is deliberate: store_users does not depend on HRM, even though admin delegation echoes the company hierarchy.

9.1 Scheduled jobs

All schedules are declared in vercel.json. Times are UTC; the business runs on Asia/Dhaka (UTC+6).

9.2 The billing cycle

9.3 Failure containment

11.1 Tests

Tests use the Node built-in runner (node --test) with tsx, so there is no test framework to maintain. The suites target domain logic (the part that is expensive to get wrong) rather than rendering.

npm run test:all

11.2 Static checks and CI

Prettier (format:check), ESLint 9 with the Next config, TypeScript via next build, and unit tests run on every push and pull request.

11.3 Seeding and environments

• scripts/seed-public.mjs, seed-crm.mjs, seed-hrm.mjs create test identities, leads, services, projects and payments; db:clean resets.
• A development environment ribbon is rendered in non-production so nobody mistakes a test deployment for the real thing.
• verify:intern-db checks that the internship migrations are present on the target database.

All screenshots below were captured from the running application against a local Supabase stack seeded with test data (test accounts, no real customer data).

13.1 Public site

Landing. Server-rendered, English by default, Bangla switch in the header.

Proposal wizard. Four steps with React Hook Form and Zod, inserting with the anon key under a narrow RLS policy.

Internships. The public program page that feeds the recruitment pipeline.

One login for every module. The proxy decides where you land.

13.2 One identity, many applications

A single account with rows in several module tables sees all of them in the Switch Application dialog. The active module is highlighted, and modules a user has no row for do not appear. This is ADR-002 and ADR-003 made visible.

13.3 Education

Customer dashboard. Active services, spend, pending payments and the package browser.

Subscriptions. The output of the daily billing cycle: paid and open invoices.

Education admin. Customers, revenue, orders and pending payments at a glance.

13.4 CRM

CRM dashboard. KPIs, trends, marketer performance and lead sources.

Leads. Ownership-based access: marketers work their own leads, admins see all.

Deals pipeline. Five open stages plus closed Won and Lost, with per-stage value totals.

Deal detail. Stage control, notes, and an append-only timeline backed by the deal_events table.

Proposal inbox. Public submissions land here for review and one-click conversion to a lead.

13.5 HRM

Super admin. People, departments, job roles, recruitment, weekly submissions and performance distribution.

Employee view. Monthly score, tier, history and trend: the same module with a very different capability set.

Recruitment. Program window, funnel counts and per-position vacancies.

Applications. Search, filter and CSV export across all pipeline states.

Application detail. Applicant data, interviews, status changes with timeline notes and structured reviewer scoring. The CV link is a short-lived signed URL.

13.6 Store

Products. Catalogue, stock tracking and pricing, gated by the product_manage permission.

Reports. Sales by employee and product, low stock, negative balances, with CSV and PDF export.

13.7 Responsive behaviour

Mobile-first layouts: the public site on a 390px phone, and a dashboard that switches to a bottom navigation bar.

<img src="https://www.wetraineducation.com/case-study/mobile-landing-home.png" alt="Public site on a phone" width="300" /> <img src="https://www.wetraineducation.com/case-study/mobile-hrm-super.png" alt="Dashboard with bottom navigation on a phone" width="300" />

A case study that only lists wins is a brochure. These are the known compromises, ranked roughly by how much I would like to fix them.

1. Make the boundary the product. Naming the four modules, their route prefixes and their tables up front turned most "where does this go?" debates into lookups.
2. Fail closed, in more than one place. The proxy, the layouts and RLS each assume the others might be wrong. The design survived a refactor of the proxy precisely because it was never the only guard.
3. RLS recursion is easy to cause and hard to see. A WITH CHECK that selects from the same table made a policy recurse infinitely; the fix was a dedicated migration and a rule to test policies against intended and unintended roles.
4. Idempotency beats scheduling precision. Once every cron job was safe to run twice, retries, manual re-runs and overlapping schedules stopped being scary.
5. Do not trust the redirect. Payment state changes only on a verified webhook; the return URL only changes what the user sees.
6. Constraints are documentation that executes. A CHECK that a week key equals its Friday date prevented an entire class of date bugs, and also caught my own stale seed file.
7. Write the rules for the agent as if for a new hire. AGENTS.md, the high-risk area list and the required reading order measurably reduced risky edits in auth and database code.
8. Keep what you cannot reverse small. Additive migrations, a test-then-live rollout and a refusal to touch applied migrations mean the riskiest operation in the system has a boring procedure.

Prerequisites

• Node.js 20+
• Docker (for the local Supabase stack) and the Supabase CLI

Run locally against a local Supabase stack

# 1. install
npm install

# 2. start Postgres, Auth and Storage locally and apply all migrations
npx supabase start

# 3. configure the app (copy, then fill in the URL and keys that `supabase start` prints)
cp .env.example .env.local

# 4. seed test users and sample data (never run against production)
npm run seed:all

# 5. run the app
npm run dev

Open http://localhost:3000. Seed scripts create test identities such as crm.admin@seed.local and hrm.super@seed.local; see scripts/seed-*.mjs for the full list and the shared test password.

Note. The checked-in supabase/seed.sql is currently out of date with the newest migrations (see debt table). If supabase start fails while seeding, set [db.seed] enabled = false in supabase/config.toml, start the stack, then use the seed:* scripts above.

Scripts

AI-assisted development

• AGENTS.md is the primary instruction file for agents; CLAUDE.md imports it.
• .mcp.json / .vscode/mcp.json configure the Next.js DevTools MCP and the Supabase MCP. Use them against local or non-production environments only.
• Repo-local guides live in skills/.

app/
├── (landing)/                 # public marketing, proposals, internships, verification
├── dashboard/
│   ├── customer/  admin/      # Education
│   ├── crm/                   # CRM        (_actions, _components, _constants, _types)
│   ├── hrm/                   # HRM        (super | admin | employee, recruitment, internship)
│   └── store/                 # Store      (_actions, _components, _lib)
├── api/                       # webhooks, cron, uploads, signed downloads
├── auth/                      # unified callback, invite, magic link, email change
├── actions/                   # public server actions (proposal, internship, locale)
└── utils/
    ├── auth/                  # roles.ts, require.ts, hrm-access.ts, crm-capabilities.ts
    └── supabase/              # client, server, admin, middleware, env
components/                    # ui/ (shadcn), shared/, hrm/, skeletons/
lib/                           # billing/, hrm/, internships/, validations/
i18n/  messages/               # next-intl config and en / bn catalogues
supabase/migrations/           # 104 forward-only migrations
scripts/                       # seed, migrate, verify, clean
tests/                         # crm, education, hrm, store, landing, ui
docs/  skills/  AGENTS.md      # durable references and agent rules
proxy.ts                       # Next.js 16 proxy (session refresh + coarse gate)
vercel.json                    # cron schedules
public/case-study/             # screenshots and diagrams used in this README

Further reading

• AGENTS.md: primary contributor and agent rules
• docs/README.md: map of the durable documentation set
• docs/ARCHITECTURE_DECISION_USERS_PROFILES.md: the original long-form ADR for ADR-002
• docs/CRITICAL_SYSTEMS.md: systems that must not regress
• docs/HRM_CRON.md: scheduled HRM logic
• docs/DATABASE_RULES.md and docs/DATABASE_MIGRATION_SAFETY.md: database safety

Built with Next.js, Supabase and a lot of care about who is allowed to see what.