Forem: Victory Lucky

Why Most Payment APIs Fail Developers Building for African Markets

Victory Lucky — Wed, 15 Apr 2026 14:34:04 +0000

There is a version of this problem that does not get talked about enough. A developer somewhere in Lagos, Nairobi, or Accra opens the docs for a payment API they want to integrate. The quickstart looks clean. The sandbox spins up fast. The first test transaction goes through without a hitch. Three weeks later, they are deep in the actual integration and everything starts falling apart in ways the documentation did not warn them about.

This is not a capability problem. The infrastructure exists. Africa processed over $1.1 trillion in mobile money transactions in 2024, more than any other region in the world — a figure documented in the Payment APIs and Interoperability report on Africa's financial infrastructure. The rails are real. The problem is that most payment APIs were designed for a different developer, in a different market, and then shipped to everyone else with the expectation that it would just work.

It does not just work.

The documentation was written for a developer in San Francisco

This sounds harsh but it is just accurate. Open the getting started guide for most major payment APIs and you will find examples that create charges in USD, reference Stripe's ecosystem as a benchmark, and use webhook examples that assume a stable server with a static IP. The error codes are documented for card-based payments. The currency handling assumes floating-point precision does not matter much because dollar amounts are stable.

None of that maps to what you are actually building.

If you are building something that pays a contractor in Ghana via MTN Mobile Money, or routes a disbursement to a bank account in Kenya while your business collects in dollars, you will not find a worked example for that in most API docs. You will find a generic /transfers endpoint and a note that says "contact support for regional availability." That note is doing a lot of work.

A Finance in Africa analysis of the developer API ecosystem found that some providers still require extended approval processes or manual credentials before you can even access certain regional endpoints. Chipper Cash's Head of Payments, who is quoted in the same piece, also cited sandbox reliability and inadequate developer support as persistent gaps. You cannot prototype your way through a manual approval gate. So before you have written a line of production code, you are already blocked.

FX volatility is a runtime problem, not a business problem

Every developer building for markets like Nigeria has had to think about exchange rates in a way that developers in stable currency markets never do. Between mid-2023 and late 2024, the naira went from roughly N460 to the dollar to nearly N1,740 — Bloomberg ranked it the worst-performing currency in 2024 after a 70 percent drop in one year. By early 2026 it had stabilized somewhere in the N1,350 to N1,450 range, but analysts documented businesses reporting FX losses in the hundreds of billions of naira across the cement, FMCG, and brewing sectors during the peak volatility window.

That is not a footnote. That is a core architectural constraint.

The problem is that most payment API docs treat exchange rates as a lookup, not a liability. You call a rates endpoint, you get a number, you show it to your user. What they do not tell you is what happens between the moment your user confirms the amount and the moment the transaction settles. In volatile markets, that spread can be meaningful.

Ola Oyetayo, CEO of Nigerian fintech Verto, explained in a Techpoint Africa interview on FX uncertainty that when the naira moves 5 to 10 percent in a matter of days, providers widen their spreads as a defensive move — not out of opportunism, but because they need to account for the slippage between the moment a customer initiates a transfer and the moment it actually settles in the global market. During high-volatility windows, pricing updates can happen minute by minute. If the API you integrated does not expose that to you, your users will see one number and receive another, and they will blame your product, not the underlying rails.

A payment API built for this market surfaces rate information that is honest about timing, expiry, and settlement risk. Most do not.

NITDA and the compliance layer most docs skip

Here is the part that catches international developers building for Nigerian users completely off guard.

Nigeria's data regulatory landscape is layered. NITDA has mandated since 2019 that subscriber and consumer data be hosted within Nigeria. The Nigeria Data Protection Act 2023 (NDPA), which supersedes the earlier NDPR, requires that organisations processing data for more than 200 Nigerian residents within a six-month period register as Data Controllers or Processors of Major Importance. As Banwo and Ighodalo's analysis of Nigeria's data localisation regime explains, the CBN's 2020 guidelines on electronic payment channels further require that domestic transactions be routed through a local switch.

This means the payment API you integrated, which is running on AWS us-east-1 and stores your transaction logs in a US-based database, may be putting you in technical breach of Nigerian data localisation rules the moment you launch with Nigerian users. A 2025 peer-reviewed study of Nigerian fintech software developers published in the Multidisciplinary Journal of Engineering, Technology and Sciences found that while engineers were generally aware of NDPR and GDPR concepts, the hardest part was implementing compliance in actual coding and system design — partly because of a lack of clear compliance documentation and region-specific toolkits.

That gap is where most payment API providers leave you. The technical documentation tells you how to make an API call. It does not tell you whether that call, and the data it generates, is compliant with the regulatory environment of the markets you are serving.

The fragmentation is not an accident

Africa is not one market. It is 54 countries with 178 different mobile money services, different currencies, different regulatory environments, and different payment rails. A payment that settles in seconds in Kenya via M-Pesa uses entirely different infrastructure than a bank transfer in South Africa or a mobile money disbursement in Ghana.

Chipper Cash's Adeeyo, quoted in the Finance in Africa developer ecosystem analysis, said publicly that fragmentation remains a major challenge both technically and institutionally, and that regulatory inconsistency across countries makes regional scaling harder. That is coming from someone operating in this market full-time. For a developer integrating a payment API, that fragmentation shows up as undocumented behaviour: a call that works in sandbox for one country silently returns a different response structure in production for another, error messages that are not granular enough to tell you whether a failure was a network issue, a KYC issue, or an FX liquidity issue.

Benjamin Fernandes, founder of NALA, documented this in a detailed post on why payments in emerging markets are still 1 percent built. Between May 2023 and January 2024, NALA averaged 25 payment partner issues per month. Webhook callbacks that did not fire. Incorrect reconciliation. APIs that confirmed delivery when the money had not moved. These are not edge cases. These are the operational reality of building on payment infrastructure that was not designed with African markets as the primary concern.

What a payment API built for this market actually looks like

It surfaces real-time exchange rates with honest settlement windows, not just a number. It handles mobile money, bank accounts, SWIFT, and local payment methods as first-class channels, not afterthoughts. It documents its regulatory posture explicitly — where data is stored, how transfers are handled under Nigerian or Kenyan data law, what compliance burden it takes on versus what it leaves with you.

It also designs its error responses for the failure modes that actually happen in these markets: FX liquidity gaps, KYC tier limitations, mobile network outages that interrupt but do not fail a transaction. The Afriex Business API is built around exactly these constraints. The exchange rates endpoint exposes live rates for supported currency pairs including NGN, KES, GHS, and GBP. The payment methods layer handles bank accounts, mobile money (including MTN Mobile Money), SWIFT, UPI, and Interac as fully supported channels, not beta features. The webhooks are signed, retried with exponential backoff, and documented for every transaction status that matters, including IN_REVIEW for compliance holds that are a real operational scenario in African markets.

That is what it looks like when the API was designed with this market in mind from the start, not retrofitted after the fact.

If you are building something that moves money across African borders and the payment API you are using does not talk about FX settlement windows, does not document its compliance posture for Nigerian or Kenyan data law, and does not have mobile money as a first-class channel, you are not using the wrong feature. You are using the wrong tool.

Build a Freelancer Payout Platform with the Afriex SDK and Next.js

Victory Lucky — Sun, 12 Apr 2026 08:32:31 +0000

Paying contractors across borders means dealing with different banking rails, payment channels, and currencies simultaneously — and most existing tools either lock you into USD-first payouts or require a separate integration per country. This article walks through a freelancer payout platform that handles all of that through a single Afriex SDK integration.

The platform is built with Next.js, Drizzle ORM, TiDB Cloud, and Better Auth. You'll clone the repo, set up your environment, and then we'll break down how everything works including the architecture, the Afriex SDK integration, webhooks, and the data flow from UI to payout execution. If you want context on what else you can build with the Afriex API, the previous article in this series covers five use cases worth reading.

By the end you'll understand how to:

Register freelancers as Afriex customers
Attach bank accounts and mobile money wallets as payout destinations
Fetch live exchange rates and trigger cross-border payouts
Receive real-time status updates via webhooks
Send email notifications when payouts are initiated or completed

The full source is on GitHub. This article covers the architecture and the interesting parts — not every line of code.

Prerequisites

Node.js v22.14+
An Afriex Business account — create one here and grab your sandbox API key from Settings > API Keys
A TiDB Serverless cluster (the free tier is sufficient for this project)
A Resend account with an API key (this is for sending emails, you can skip if you want)

Architecture

The app uses a layered architecture. Every layer has one job:

Browser  →  Hook  →  Service  →  API Route  →  Repository (DB)
                                            →  DAL (Afriex SDK)

Layer	What it does
Hook	React Query wrapper — caching, loading states, cache invalidation
Service	Thin HTTP client — calls your own API routes
API Route	Validates input, calls the repository and DAL, returns JSON
Repository	Reads/writes your database through Drizzle
Data Access Layer (DAL)	Calls the Afriex SDK — the only layer that touches the external API

This separation matters because your database is your source of truth for UI state, while the Afriex API is your source of truth for payout execution. The API route coordinates both.

Project Setup

Clone the repo and install dependencies:

git clone https://github.com/codewithveek/afriex-payout-platform.git
cd afriex-payout-platform
pnpm install

Copy the example environment file and fill in your credentials:

cp .env.example .env.local

DATABASE_URL=mysql://user:pass@gateway.tidbcloud.com:4000/payout_platform?ssl={"rejectUnauthorized":true}
BETTER_AUTH_SECRET=your-random-secret
BETTER_AUTH_URL=http://localhost:3200
AFRIEX_API_KEY=your-sandbox-api-key
AFRIEX_ENVIRONMENT=staging
AFRIEX_WEBHOOK_PUBLIC_KEY=your-webhook-public-key
RESEND_API_KEY=your-resend-api-key
EMAIL_FROM=Payouts <noreply@yourdomain.com>

Run the database migration and start the dev server:

pnpm run db:migrate
pnpm dev

The rest of this article walks through how the codebase works — starting from the database layer up to the Afriex SDK integration and webhooks.

Database Layer

Connection

TiDB Cloud provides a MySQL-compatible serverless database. Connect it with Drizzle:

// src/db/index.ts
import { connect } from "@tidbcloud/serverless";
import { drizzle } from "drizzle-orm/tidb-serverless";
import * as schema from "./schema";

const client = connect({ url: process.env.DATABASE_URL! });
export const db = drizzle(client, { schema });

Schema

The application tables mirror the Afriex domain model. Each record stores the Afriex-assigned ID so you can call the SDK later:

// src/db/schema.ts (application tables only — Better Auth tables omitted for brevity)

export const customers = mysqlTable("customers", {
  id: varchar("id", { length: 36 }).primaryKey(),
  afriexCustomerId: varchar("afriex_customer_id", { length: 255 })
    .notNull()
    .unique(),
  fullName: varchar("full_name", { length: 255 }).notNull(),
  email: varchar("email", { length: 255 }).notNull(),
  phone: varchar("phone", { length: 50 }).notNull(),
  countryCode: varchar("country_code", { length: 2 }).notNull(),
  createdByUserId: varchar("created_by_user_id", { length: 36 })
    .notNull()
    .references(() => users.id),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().onUpdateNow().notNull(),
});

export const paymentMethods = mysqlTable("payment_methods", {
  id: varchar("id", { length: 36 }).primaryKey(),
  afriexPaymentMethodId: varchar("afriex_payment_method_id", { length: 255 })
    .notNull()
    .unique(),
  customerId: varchar("customer_id", { length: 36 })
    .notNull()
    .references(() => customers.id, { onDelete: "cascade" }),
  channel: varchar("channel", { length: 50 }).notNull(),
  accountName: varchar("account_name", { length: 255 }).notNull(),
  accountNumber: varchar("account_number", { length: 255 }).notNull(),
  countryCode: varchar("country_code", { length: 2 }).notNull(),
  institutionName: varchar("institution_name", { length: 255 }),
  // ...timestamps
});

export const transactions = mysqlTable("transactions", {
  id: varchar("id", { length: 36 }).primaryKey(),
  afriexTransactionId: varchar("afriex_transaction_id", { length: 255 })
    .notNull()
    .unique(),
  customerId: varchar("customer_id", { length: 36 })
    .notNull()
    .references(() => customers.id),
  paymentMethodId: varchar("payment_method_id", { length: 36 })
    .notNull()
    .references(() => paymentMethods.id),
  reference: varchar("reference", { length: 64 }).notNull().unique(),
  sourceCurrency: varchar("source_currency", { length: 3 }).notNull(),
  destinationCurrency: varchar("destination_currency", { length: 3 }).notNull(),
  destinationAmount: decimal("destination_amount", { precision: 18, scale: 2 }),
  status: varchar("status", { length: 50 }).default("PENDING").notNull(),
  createdByUserId: varchar("created_by_user_id", { length: 36 })
    .notNull()
    .references(() => users.id),
  // ...timestamps
});

The key column is afriexCustomerId (and its equivalents on the other tables). When the Afriex API creates a resource, it returns an ID. You store that ID in your database so every subsequent SDK call uses it. Your own id column is for your UI and internal joins.

Afriex SDK Integration

This is the core of the application. The SDK is initialized once and used across four Data Access Layer (DAL) files.

SDK Initialization

// src/lib/afriex.ts
import { Afriex } from "@afriex/sdk";

export const afriex = new Afriex({
  apiKey: process.env.AFRIEX_API_KEY!,
  environment:
    (process.env.AFRIEX_ENVIRONMENT as "staging" | "production") ?? "staging",
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
  },
  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY,
});

The SDK handles authentication, retries, and webhook signature verification. The webhookPublicKey is needed later for verifying incoming webhook payloads.

DAL: Customers

Each DAL file wraps one SDK namespace. They return { data, error } so the API route can decide how to respond without try/catching everywhere:

// src/lib/dal/customers.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError } from "@/lib/utils";
import type { CreateCustomerInput } from "@/lib/schemas/customer.schema";

export async function createAfrexCustomer(input: CreateCustomerInput) {
  try {
    const customer = await afriex.customers.create(input);
    return { data: customer };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

DAL: Payment Methods

// src/lib/dal/payment-methods.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError } from "@/lib/utils";
import type { CreatePaymentMethodInput } from "@/lib/schemas/payment-method.schema";

export async function createAfrexPaymentMethod(
  input: CreatePaymentMethodInput,
  afriexCustomerId: string
) {
  try {
    const pm = await afriex.paymentMethods.create({
      customerId: afriexCustomerId,
      channel: input.channel,
      accountName: input.accountName,
      accountNumber: input.accountNumber,
      countryCode: input.countryCode,
      institution: {
        institutionCode: input.institutionCode,
        institutionName: input.institutionName ?? input.institutionCode,
      },
    });
    return { data: pm };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

DAL: Transactions (Payouts)

This is where payouts actually happen. The SDK's transactions.create call with type: "WITHDRAW" sends money to the freelancer's payment method:

// src/lib/dal/transactions.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError, generateIdempotencyKey } from "@/lib/utils";

export async function createAfriexTransaction(params: {
  afriexCustomerId: string;
  afriexPaymentMethodId: string;
  destinationAmount: number;
  sourceCurrency: string;
  destinationCurrency: string;
  reference: string;
}) {
  try {
    const idempotencyKey = generateIdempotencyKey(params.reference);

    const tx = await afriex.transactions.create({
      type: "WITHDRAW",
      customerId: params.afriexCustomerId,
      destinationId: params.afriexPaymentMethodId,
      sourceAmount: `${params.destinationAmount}`,
      destinationAmount: `${params.destinationAmount}`,
      sourceCurrency: params.sourceCurrency,
      destinationCurrency: params.destinationCurrency,
      meta: {
        merchantId: params.reference,
        idempotencyKey,
        narration: `Payout — ${params.reference}`,
        reference: params.reference,
      },
    });

    return { data: tx };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

The idempotencyKey ensures that if a network error causes a retry, Afriex won't create a duplicate transaction. It's derived from the reference string so the same reference always produces the same key:

// src/lib/utils/index.ts
export function generateIdempotencyKey(seed?: string): string {
  if (seed) return `idem-${seed}`;
  return `idem-${crypto.randomUUID()}`;
}

DAL: Exchange Rates

Before sending a payout, you may want to see the current exchange rate:

// src/lib/dal/rates.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError } from "@/lib/utils";

export async function getAfrexRate(from: string, to: string) {
  try {
    const result = await afriex.rates.getRates({
      fromSymbols: from,
      toSymbols: to,
    });
    const rate = result?.rates?.[from]?.[to];
    if (!rate) return { error: `Rate for ${from}/${to} not available` };
    return { data: { from, to, rate: parseFloat(rate) } };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

export async function convertAfrexCurrency(
  amount: number,
  from: string,
  to: string
) {
  try {
    const convertedAmount = await afriex.rates.convert(amount, from, to);
    const rateResult = await getAfrexRate(from, to);
    return {
      data: {
        from,
        to,
        rate: rateResult.data?.rate ?? 0,
        amount,
        convertedAmount,
      },
    };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

API Routes

API routes coordinate validation, database writes, and SDK calls. Here's the transaction (payout) route — the most complex one — to show the pattern:

// src/app/api/transactions/route.ts
import { NextRequest, NextResponse } from "next/server";
import { createTransactionSchema } from "@/lib/schemas/transaction.schema";
import { createAfriexTransaction } from "@/lib/dal/transactions.dal";
import { insertTransaction } from "@/repositories/transaction.repository";
import { findCustomerById } from "@/repositories/customer.repository";
import { findPaymentMethodsByCustomer } from "@/repositories/payment-method.repository";
import { sendPayoutInitiatedEmail } from "@/lib/email";
import { getRequiredSession } from "@/lib/utils/auth";

export async function POST(req: NextRequest) {
  const session = await getRequiredSession();
  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const body = await req.json();
  const result = createTransactionSchema.safeParse(body);
  if (!result.success) {
    return NextResponse.json(
      { error: result.error.flatten().fieldErrors },
      { status: 400 }
    );
  }

  // 1. Look up the customer in the database to get their Afriex IDs
  const customer = await findCustomerById(result.data.customerId);
  if (!customer) {
    return NextResponse.json({ error: "Customer not found" }, { status: 404 });
  }

  const paymentMethods = await findPaymentMethodsByCustomer(customer.id);
  const paymentMethod = paymentMethods.find(
    (pm) => pm.id === result.data.paymentMethodId
  );
  if (!paymentMethod) {
    return NextResponse.json(
      { error: "Payment method not found" },
      { status: 404 }
    );
  }

  // 2. Create the payout in Afriex
  const afriexResult = await createAfriexTransaction({
    afriexCustomerId: customer.afriexCustomerId,
    afriexPaymentMethodId: paymentMethod.afriexPaymentMethodId,
    destinationAmount: result.data.destinationAmount,
    sourceCurrency: result.data.sourceCurrency,
    destinationCurrency: result.data.destinationCurrency,
    reference: result.data.reference,
  });

  if (afriexResult.error) {
    return NextResponse.json({ error: afriexResult.error }, { status: 502 });
  }

  // 3. Persist the transaction to the database
  const transaction = await insertTransaction({
    afriexTransactionId: afriexResult.data!.transactionId,
    customerId: customer.id,
    paymentMethodId: paymentMethod.id,
    reference: result.data.reference,
    sourceCurrency: result.data.sourceCurrency,
    destinationCurrency: result.data.destinationCurrency,
    destinationAmount: result.data.destinationAmount.toString(),
    createdByUserId: session.user.id,
  });

  // 4. Send a notification email
  await sendPayoutInitiatedEmail({
    to: session.user.email,
    freelancerName: customer.fullName,
    amount: result.data.destinationAmount.toString(),
    currency: result.data.destinationCurrency,
    reference: result.data.reference,
    transactionId: afriexResult.data!.transactionId,
  });

  return NextResponse.json({ data: transaction }, { status: 201 });
}

The pattern is always the same:

Authenticate — getRequiredSession()
Validate — Zod schema
Resolve — look up records in the database to get Afriex IDs
Call Afriex — through the DAL
Persist — save to your database
Side effects — email, logging, etc.

The customer and payment method routes follow this exact pattern. See src/app/api/customers/route.ts and src/app/api/payment-methods/route.ts in the repo.

Webhooks

Webhooks are how Afriex tells you what happened to a payout after you created it. A transaction's status moves through PENDING → PROCESSING → COMPLETED (or FAILED), and Afriex sends a signed HTTP POST for each transition.

The SDK provides a verifyAndParse method that checks the webhook signature and returns the parsed payload:

// src/app/api/webhooks/route.ts
import { NextRequest, NextResponse } from "next/server";
import { afriex } from "@/lib/afriex";
import {
  updateTransactionStatus,
  findTransactionForEmail,
} from "@/repositories/transaction.repository";
import { sendPayoutStatusEmail } from "@/lib/email";
import { WebhookPayload } from "@afriex/sdk";

export async function POST(req: NextRequest) {
  const signature = req.headers.get("x-webhook-signature");
  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 401 });
  }

  // 1. Verify the signature and parse the payload
  const rawBody = await req.text();
  let webhookPayload: WebhookPayload;
  try {
    webhookPayload = afriex.webhooks.verifyAndParse(rawBody, signature);
  } catch {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  const eventType = webhookPayload.event;
  // 2. Handle transaction status updates
  if (
    eventType === "TRANSACTION.UPDATED" ||
    eventType === "TRANSACTION.CREATED"
  ) {
    const { transactionId, status } = event.data as {
      transactionId: string;
      status: string;
    };

    await updateTransactionStatus(transactionId, status);

    // Send email on terminal statuses
    const terminalStatuses = ["COMPLETED", "SUCCESS", "FAILED", "REJECTED"];
    if (terminalStatuses.includes(status)) {
      const tx = await findTransactionForEmail(transactionId);
      if (tx) {
        await sendPayoutStatusEmail({
          to: tx.userEmail,
          freelancerName: tx.customerName,
          amount: tx.destinationAmount,
          currency: tx.destinationCurrency,
          reference: tx.reference,
          status,
        });
      }
    }
  }

  // 3. Handle customer and payment method sync events
  if (eventType === "CUSTOMER.UPDATED") {
    // Sync name/email changes back to the DB
  }
  if (eventType === "CUSTOMER.DELETED") {
    // Remove from the DB
  }
  if (eventType === "PAYMENT_METHOD.DELETED") {
    // Remove from the DB
  }

  return NextResponse.json({ received: true });
}

Three things to note:

Raw body — you must read req.text(), not req.json(). The SDK verifies the signature against the raw string. Parsing first would change the byte representation.
Terminal statuses — only send a "payout completed/failed" email on final statuses. Intermediate statuses like PROCESSING are handled silently.
Customer/Payment Method sync — Afriex can update or delete these resources from its side. The webhook handler keeps your DB in sync.

To test webhooks locally, expose your dev server with ngrok:

npx ngrok http 3200

Copy the HTTPS URL + /api/webhooks into your Afriex dashboard under Developers > Webhooks. Paste the public key into .env.local as AFRIEX_WEBHOOK_PUBLIC_KEY.

Client Layer

The client layer follows a three-step chain: Hook → Service → API route. Each step does one thing.

Service (HTTP Client)

A thin wrapper around fetch that extracts .data from responses and throws on errors:

// src/services/api-client.ts
async function request<T>(
  method: string,
  url: string,
  body?: unknown
): Promise<T> {
  const res = await fetch(url, {
    method,
    headers: { "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) {
    throw new Error(
      typeof json.error === "string" ? json.error : "Request failed"
    );
  }
  return json.data as T;
}

export const http = {
  get: <T>(url: string) => request<T>("GET", url),
  post: <T>(url: string, body: unknown) => request<T>("POST", url, body),
  patch: <T>(url: string, body: unknown) => request<T>("PATCH", url, body),
  delete: <T>(url: string) => request<T>("DELETE", url),
};

Service Files

Each resource gets a service file that maps CRUD operations to API routes:

// src/services/customer.api.ts
import { http } from "./api-client";
import type { CreateCustomerInput } from "@/lib/schemas/customer.schema";
import type { Customer } from "@/db/schema";

export const customerApi = {
  create: (data: CreateCustomerInput) =>
    http.post<Customer>("/api/customers", data),
  list: () => http.get<Customer[]>("/api/customers"),
  get: (id: string) => http.get<CustomerDetail>(`/api/customers/${id}`),
  delete: (id: string) => http.delete<void>(`/api/customers/${id}`),
};

The payment method, transaction, and rates services follow the same shape. See src/services/ in the repo.

Hooks (React Query)

Hooks wrap services with TanStack Query for caching, loading states, and cache invalidation:

// src/hooks/useCustomer.ts
"use client";

import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { customerApi } from "@/services/customer.api";
import type { CreateCustomerInput } from "@/lib/schemas/customer.schema";

export function useCustomers() {
  return useQuery({
    queryKey: ["customers"],
    queryFn: () => customerApi.list(),
  });
}

export function useCreateCustomer() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: CreateCustomerInput) => customerApi.create(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["customers"] });
    },
  });
}

The onSuccess callback invalidates the query cache so the customer list refreshes automatically after a creation. Every mutation hook follows this pattern.

Authentication

The app uses Better Auth for email/password authentication. Setup involves three files:

Server — src/lib/auth.ts: Initializes Better Auth with the Drizzle adapter, pointing at the auth tables in your schema.

Client — src/lib/auth-client.ts: Exports signIn, signUp, signOut, and useSession for use in React components.

Middleware — src/proxy.ts: Redirects unauthenticated users away from /dashboard/* routes.

// src/proxy.ts
import { getSessionCookie } from "better-auth/cookies";
import { NextRequest, NextResponse } from "next/server";

export async function proxy(request: NextRequest) {
  const sessionCookie = getSessionCookie(request);
  if (!sessionCookie) {
    return NextResponse.redirect(new URL("/sign-in", request.url));
  }
  return NextResponse.next();
}

export const config = { matcher: ["/dashboard/:path*"] };

Full auth setup including the sign-in/sign-up pages is in the repo.

Email Notifications

Payout notifications use Resend with React Email templates. Two emails are sent during a payout lifecycle:

Payout initiated — sent immediately after creating the transaction
Payout completed/failed — sent when the webhook receives a terminal status

// src/lib/email.ts
import { Resend } from "resend";
import { PayoutInitiated } from "@/emails/PayoutInitiated";
import { PayoutCompleted } from "@/emails/PayoutCompleted";

const resend = new Resend(process.env.RESEND_API_KEY!);
const FROM = process.env.EMAIL_FROM ?? "Payouts <noreply@example.com>";

export async function sendPayoutInitiatedEmail(params: {
  to: string;
  freelancerName: string;
  amount: string;
  currency: string;
  reference: string;
  transactionId: string;
}) {
  const { error } = await resend.emails.send({
    from: FROM,
    to: params.to,
    subject: `Payout initiated — ${params.reference}`,
    react: PayoutInitiated(params),
  });

  if (error) {
    console.error("[email] sendPayoutInitiatedEmail failed:", error);
  }
}

Note that email failures are logged but not thrown. A failed email should never block a successful payout.

The React Email templates are straightforward HTML-in-JSX. See src/emails/ for both templates.

Validation Schemas

All input validation uses Zod. The schemas are shared between the API route (server-side validation) and the form (client-side validation via @hookform/resolvers):

// src/lib/schemas/customer.schema.ts
import { z } from "zod";

export const createCustomerSchema = z.object({
  fullName: z.string().min(2).max(100),
  email: z.string().email(),
  phone: z
    .string()
    .regex(
      /^\+[1-9]\d{1,14}$/,
      "Phone must contain country code e.g. +2348012345678"
    ),
  countryCode: z.string().length(2),
});

export type CreateCustomerInput = z.infer<typeof createCustomerSchema>;

// src/lib/schemas/transaction.schema.ts
import { z } from "zod";

export const createTransactionSchema = z.object({
  customerId: z.string().min(1),
  paymentMethodId: z.string().min(1),
  destinationAmount: z.number().positive(),
  sourceCurrency: z.string().length(3),
  destinationCurrency: z.string().length(3),
  reference: z.string().min(1).max(64),
});

export type CreateTransactionInput = z.infer<typeof createTransactionSchema>;

The payment method schema is in the repo.

Repositories

Repositories handle all database reads and writes. They never call the Afriex SDK — that's the DAL's job. Here's the customer repository to show the pattern:

// src/repositories/customer.repository.ts
import { db } from "@/db";
import { customers } from "@/db/schema";
import { eq } from "drizzle-orm";
import { randomUUID } from "crypto";

export async function insertCustomer(data: {
  afriexCustomerId: string;
  fullName: string;
  email: string;
  phone: string;
  countryCode: string;
  createdByUserId: string;
}) {
  const id = randomUUID();
  await db.insert(customers).values({ id, ...data });

  const [customer] = await db
    .select()
    .from(customers)
    .where(eq(customers.id, id))
    .limit(1);

  return customer;
}

export async function findCustomersByUser(userId: string) {
  return db
    .select()
    .from(customers)
    .where(eq(customers.createdByUserId, userId));
}

export async function findCustomerById(id: string) {
  const [customer] = await db
    .select()
    .from(customers)
    .where(eq(customers.id, id))
    .limit(1);
  return customer ?? null;
}

The transaction and payment method repositories follow the same CRUD pattern. See src/repositories/.

The Dashboard

The UI consists of a sidebar shell, an overview page with metric cards and a transactions table, and a modal for the new payout flow. The modal consists of three steps: register a freelancer → attach a payment method → send the payout.

All form components use React Hook Form with the Zod schemas defined above, and the mutation hooks from the hooks layer. There's no direct fetch or useState for loading in any form — React Query handles all of that.

The full UI code is in the repo:

Dashboard layout + sidebar
Form components
Dashboard components (MetricCard, TransactionsTable, NewPayoutDrawer)

Deploying

vercel

Add your environment variables in Project > Settings > Environment Variables. Use production credentials for both Afriex and TiDB Cloud.

Update your Afriex webhook URL to the Vercel deployment URL (https://your-app.vercel.app/api/webhooks) and copy the webhook public key.

Wrapping Up

The architecture pattern in this article: your database owns the UI state, the Afriex SDK owns the payout execution, and the API route coordinates both — that's the key takeaway regardless of what you build on top of it.
It keeps each layer testable and replaceable, and it means that when Afriex adds a new payment channel or webhook event, you know exactly which file to touch.

The full project is on GitHub. The next article in this series covers the international payroll system — same architecture, significantly higher compliance requirements. If you have questions in the meantime, drop them in the comments or reach out on X @codewithveek.

5 Products You Can Build with Afriex Cross-Border Payment API

Victory Lucky — Thu, 02 Apr 2026 02:09:31 +0000

Sending money across borders is still unnecessarily hard. Between fragmented banking rails, FX volatility, compliance overhead, and the constant managing of different payment channels per country, most businesses just give up and build the bare minimum. The Afriex cross-border payment API was built to abstract most of that complexity for you.

What you get is an international payout platform API which supports customer management with KYC integration, multi-channel payment methods (bank accounts, mobile money, SWIFT, UPI, Interac, WeChat Pay, and crypto wallets), a real-time FX rate API, deposits, withdrawals, and webhook-based event notifications — all in one integration. That is a wide enough surface to build serious products on top of.

Here are five products worth building on top of it.

1. A Cross-Border Freelancer Payout Platform

The problem it solves

A freelancer in Kenya finishing a project for a client in the UK still has to go through a painful process to get paid — wire transfers with high fees, days-long settlement times, or stablecoin workarounds that require crypto literacy. Platforms that manage remote teams and contractors across multiple countries deal with this at scale, and it is one of the most common reasons contractor retention drops. What most of these platforms are really missing is a solid contractor payment API underneath them.

How the Afriex API makes this work

The core flow is straightforward. When a freelancer signs up, you register them as a customer via the Create Customer endpoint, pass optional KYC details through the same request, and attach their preferred payment method. The built-in KYC integration means you are not stitching together a separate identity verification layer, it is part of the same customer object. The API supports bank accounts across supported markets in West Africa and Southern Africa, plus SWIFT for international bank transfers, mobile money (MTN and others in Ghana, for example), and even UPI for Indian recipients. You store the resulting paymentMethodId against their profile in your system.

When a client approves a project and triggers a payout, you call the Create Transaction endpoint with type: WITHDRAW, pass the freelancer's customerId and their destinationId (the stored payment method), specify the source and destination currencies, and the transfer goes through. Webhook events on transaction.completed or transaction.failed let you update the freelancer's dashboard in real time without polling.

Before processing, you can pull live rates from the Exchange Rates endpoint to show the freelancer exactly what they will receive before they confirm — no surprises at settlement.

Why it is a business

Platforms like this typically charge a percentage fee on every payout or mark up the exchange rate slightly. With the Afriex rates endpoint giving you real-time FX data, you have full visibility into your margin on every transaction.

2. A Global Creator Monetization Tool

The problem it solves

Content creators, newsletter writers, indie game developers, and digital artists increasingly have international audiences. Most monetization tools (Patreon, Gumroad, etc.) are built for USD-first payouts and do very little for a creator in Ghana trying to collect revenue from subscribers in the US, Germany, and Canada simultaneously, then cash out to a local mobile money wallet.

How the Afriex API makes this work

You build a lightweight "creator wallet" product. Each creator gets onboarded as a customer in your system via the Afriex API. When a subscriber makes a payment (through whatever checkout you have on your platform), you deposit into the creator's account balance. When the creator wants to cash out, they choose their preferred withdrawal method, which could be bank account, mobile money, or SWIFT, and you trigger a withdrawal transaction to the saved payment method.

The multi-channel nature of the payment methods endpoint is what makes this particularly powerful here. The same codebase handles a creator in South Africa withdrawing to a local bank account, a creator in Uganda withdrawing via mobile money, and a creator in India withdrawing via UPI. You are not building separate integrations per country, just one payment method creation flow, different channel values.

The crypto wallet support (USDT and USDC on Ethereum Mainnet and other supported networks) also opens up a path for creators who want stablecoin payouts, USDC payout in particular is a real preference in markets where local currency volatility makes holding fiat unattractive.

Why it is a business

Creator tools monetize on platform fees, subscription tiers for advanced analytics, or a small percentage on each payout. The fact that you can serve creators across Africa, India, the UK, and North America without per-country integrations is what makes the unit economics work at smaller scale.

3. An International Payroll Tool for Remote-First Companies

The problem it solves

Running remote team payroll is one of the more painful operational problems a company can have. Most existing global payroll API tools handle local compliance well but fall apart when a company has employees or contractors across multiple African countries, Southeast Asia, and Europe at the same time. The alternative is using a mix of different providers per region, which creates reconciliation nightmares.

How the Afriex API makes this work

You build a payroll orchestration layer on top of the Afriex API. HR admins define salary amounts and payment schedules. Employees register their payout preferences (bank account, mobile money, SWIFT). On payroll run day, your system iterates over the payroll records, calls the Create Transaction endpoint for each employee with the appropriate currencies, and fires them off. The meta field on the transaction lets you attach a reference (e.g. payroll-2026-04-employee-123) and an idempotency key, which is important for payroll as you do not want double-pays if a request is retried.

Webhook events handle the status updates. When a transaction completes or fails, the webhook fires and your system updates the payroll run record accordingly. Failed transactions can be flagged for manual review or automatic retry.

The balance endpoint lets you monitor your funding account in real time so payroll runs do not fail mid-flight because of insufficient balance, additionally you can build alerts that notify finance teams when the account drops below a threshold.

Why it is a business

This puts you in direct competition with tools like Deel or Remote in the contractor management and remote team payroll space, but built for companies with significant headcount in African and South/Southeast Asian markets specifically. The fact that the underlying contractor payment API handles mobile money, SWIFT, and bank accounts in the same integration is the differentiator. Pricing models here are typically per-employee per-month or a percentage of total payroll processed.

4. An FX Rate Tracker and Currency Conversion App

The problem it solves

Businesses that deal with cross-border transactions — importers, exporters, procurement teams, and travel agencies — need to monitor exchange rates across multiple currency pairs and make decisions based on them. Most FX rate API tools either cover major global pairs (USD/EUR/GBP) and largely ignore African currencies, or they provide rates that are not close to what you actually get when you execute a transaction.

How the Afriex API makes this work

The Exchange Rates endpoint returns real-time rates for supported currency pairs, see the example in the documentation which shows pairs including NGN, KES, GBP, EUR, CAD, and USD. You can filter to specific fromSymbols and toSymbols to only fetch the pairs your users care about.

Build a simple dashboard that polls this endpoint on a schedule, stores the historical data on your end, and surfaces rate trends over time. You can also include alerts so users get notified when a target rate is hit (e.g. "notify me when USD to NGN crosses 1500"). You could also add a conversion calculator that uses live rates, and if you connect this to an actual transaction execution flow, users can set rate targets and trigger a real transfer through the Afriex transactions API when the rate moves in their favour.

This is also a natural product to embed inside a larger B2B tool. An invoicing platform serving import/export businesses could surface live FX rates inline so clients can see the landed cost of an invoice before paying.

Why it is a business

Standalone FX tools monetize through premium alert tiers, API access for other developers, and affiliate or spread arrangements if they also execute transactions. The embedded version monetizes as a feature that justifies a higher tier of a broader product.

5. A Regional E-Commerce Checkout and Settlement Layer

The problem it solves

A merchant selling physical or digital products to customers across multiple African countries and the diaspora (UK, US, Canada) faces a fragmentation problem at checkout. Local customers in Ghana want to pay by mobile money. Customers in South Africa want bank transfers. The diaspora wants to pay in USD or GBP. Most off-the-shelf checkout tools force the merchant to either limit their market or manage multiple payment processors with separate dashboards and settlement cycles.

How the Afriex API makes this work

You build a unified checkout abstraction. When a customer initiates a purchase, your checkout flow creates them as an Afriex customer (or retrieves the existing record) and presents payment options based on their country. The supported channels in the payment method API include BANK_ACCOUNT, MOBILE_MONEY, SWIFT, INTERAC, UPI, and WE_CHAT, which then map neatly to the dominant payment preferences in each supported market.

For merchants who want to collect payments (rather than just disburse them), the virtual account API endpoint lets you provision a dedicated virtual bank account per customer or per transaction for supported currencies (USD, NGN, GBP, EUR). The customer pays into the virtual account, the deposit is detected, and your system triggers the order fulfillment flow via a webhook event.

For the merchant's settlement, you use the withdrawal flow to move funds to wherever they need them which could be local bank account, SWIFT, or a stablecoin payout to a USDT or USDC wallet if they prefer to hold in stable assets.

Why it is a business

Payment infrastructure products typically take a percentage of GMV, charge fixed fees per transaction, or both. The differentiation here is the breadth of payment methods in a single integration, which lets merchants who previously needed two or three different processors consolidate into one.

Getting Started

Everything you need to get started is in the Afriex Business API documentation. If you are building in TypeScript or JavaScript, there is also an official SDK that gives you full type definitions, built-in retry logic, and a clean interface over the REST API. You can create a business account here, and start building with the API in sandbox in a few minutes, then switch to production environment when you're ready.

import { AfriexSDK } from "@afriex/sdk";

const afriex = new AfriexSDK({
  apiKey: "YOUR_API_KEY",
  environment: "staging", // switch to 'production' when ready
});

Regardless of which product you are building, whether it's a freelancer payout platform, a remote team payroll tool, or a virtual account API integration, you are working with the same four core resources: Customers, Payment Methods, Transactions, and Webhooks. The use case changes; the primitives stay the same.

In the next article in this series we will walk through building the freelancer payout platform end to end, from customer onboarding and KYC to real-time transaction status on a dashboard. Keep an eye out for it.

Have any questions or need assistance with the API integration? Drop them in the comments or reach out to me on X @codewithveek and I will be glad to help.

From RAG to Agents: How TiDB Powers Modern AI Applications

Victory Lucky — Wed, 18 Feb 2026 11:34:03 +0000

Building AI applications today feels different than it did even a year ago. We've gone from simple chatbot wrappers around LLM APIs to building systems that need memory, context, and increasingly complex data patterns. The problem? Most of us end up juggling a vector database for embeddings, a relational database for structured data, maybe a cache layer for performance, and a bunch of ETL pipelines trying to keep everything synchronized. It works, but it's a lot.

TiDB offers a different approach: a distributed SQL database with native vector search and HTAP (Hybrid Transactional/Analytical Processing) capabilities that can serve as the foundation for modern AI applications. In this post, we'll explore how TiDB addresses the unique challenges of building AI systems in 2026, from RAG pipelines to autonomous agents.

The AI Data Problem: Why Your Stack Keeps Growing

If you're building AI apps right now, your architecture probably looks something like this:

Vector database (Pinecone, Weaviate, Qdrant) for semantic search
Relational database (PostgreSQL, MySQL) for structured data
Analytics database (Snowflake, ClickHouse) for insights
Cache (Redis) for performance
ETL pipelines trying to keep it all synchronized

Each tool is good at what it does. But the integration work? That's where things get messy. Take a customer support AI as an example. It needs to:

Find semantically similar support tickets (vector search)
Filter by customer tier and product version (relational)
Analyze resolution patterns in real-time (analytics)
Serve everything with sub-second latency

The traditional approach means data living in multiple places, syncing constantly, with consistency issues and latency at every boundary. This is the problem TiDB's architecture solves.

TiDB's Architecture: Not Built for AI, But Perfect for It

TiDB wasn't originally designed for the AI boom - it's been around since before "RAG" was even a term. But its architecture happens to map really well to what modern AI applications need:

1. MySQL Compatibility + Horizontal Scaling

TiDB speaks the MySQL protocol. Your ORMs work. Your existing tools work. Your team's MySQL knowledge transfers directly. The difference? It scales horizontally without you having to manually shard anything.

-- Standard MySQL syntax works
CREATE TABLE conversations (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id BIGINT NOT NULL,
    session_id VARCHAR(255),
    message TEXT,
    response TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_user_session (user_id, session_id)
);

As your AI application grows from thousands to millions of users, you add nodes rather than rewrite your schema.

2. Native Vector Search (No Separate Database Needed)

Starting with version 7.4, TiDB has native vector support. You can store embeddings right alongside your regular data and search them with SQL. No separate vector database to keep in sync.

-- Create a table with embeddings
CREATE TABLE documents (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    content TEXT,
    embedding VECTOR(1536),  -- OpenAI ada-002 dimension
    category VARCHAR(100),
    created_at TIMESTAMP,
    VECTOR INDEX idx_embedding (embedding)
);

-- Insert a document with its embedding
INSERT INTO documents (content, embedding, category) 
VALUES (
    'TiDB supports HTAP workloads...',
    '[0.123, -0.456, 0.789, ...]',  -- 1536-dim vector
    'documentation'
);

-- Semantic search with structured filters
SELECT id, content, category,
       VEC_COSINE_DISTANCE(embedding, '[0.1, -0.2, ...]') AS similarity
FROM documents
WHERE category = 'documentation'
  AND created_at > NOW() - INTERVAL 30 DAY
ORDER BY similarity ASC
LIMIT 10;

Compare this to managing Pinecone + PostgreSQL separately:

# Traditional approach: juggling two systems
# Step 1: Query Pinecone for vectors
vector_results = pinecone_index.query(
    vector=embedding,
    top_k=100,  # Have to over-fetch since we'll filter later
    include_metadata=True
)

# Step 2: Get IDs and query Postgres for filtered results  
ids = [r.id for r in vector_results]
filtered_results = db.execute("""
    SELECT * FROM documents 
    WHERE id IN (%s) 
      AND category = 'documentation'
      AND created_at > NOW() - INTERVAL '30 days'
    ORDER BY ARRAY_POSITION(%s, id)
""", (ids, ids))

# Hope nothing changed between the two queries...

With TiDB, it's one query. No sync issues. No race conditions.

3. HTAP: Run Analytics on Live Data (No ETL)

This is where TiDB gets interesting. It has two storage engines working together:

TiKV (row-based) for transactions
TiFlash (columnar) for analytics

You write to TiKV, query analytics from TiFlash. They stay in sync automatically. No ETL pipeline, no separate data warehouse, no stale data.

-- Analyze AI agent performance in real-time
SELECT 
    agent_type,
    DATE(created_at) as date,
    COUNT(*) as total_interactions,
    AVG(response_time_ms) as avg_response_time,
    AVG(user_satisfaction_score) as avg_satisfaction,
    PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY response_time_ms) as p95_latency
FROM agent_interactions
WHERE created_at > NOW() - INTERVAL 7 DAY
GROUP BY agent_type, DATE(created_at)
ORDER BY date DESC;

This query runs on TiFlash (the columnar engine) while your app keeps writing to TiKV (the row engine). They don't interfere with each other. No need for Snowflake or ClickHouse on the side.

Real-World AI Use Cases with TiDB

RAG Applications (The Most Common Use Case)

RAG is basically the standard way to build with LLMs now. And RAG needs both semantic search and structured filtering - which is exactly what TiDB does well:

-- Knowledge base table with vectors and metadata
CREATE TABLE knowledge_base (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(500),
    content TEXT,
    embedding VECTOR(1536),
    source VARCHAR(255),
    last_updated TIMESTAMP,
    access_level ENUM('public', 'internal', 'restricted'),
    VECTOR INDEX idx_embedding (embedding)
);

-- RAG retrieval query: semantic + structured filters
SELECT 
    id, 
    title, 
    content,
    VEC_COSINE_DISTANCE(embedding, :query_embedding) AS relevance
FROM knowledge_base
WHERE access_level IN ('public', 'internal')
  AND last_updated > :cutoff_date
ORDER BY relevance ASC
LIMIT 5;

Postgres with pgvector can do this too, but it doesn't scale well. PostgreSQL's vector indexes (IVFFlat, HNSW) aren't built for distribution - you hit a ceiling pretty quickly. TiDB's distributed architecture means your knowledge base can actually grow to billions of documents without a rewrite.

AI Agent Memory (The Future of AI Apps)

If you're building agents that run for more than one interaction, they need memory. Not just short-term chat history - actual long-term memory about users, facts, past decisions, all of it. This breaks down into:

Episodic memory: What happened in past conversations
Semantic memory: Facts learned about the user or context
Working memory: Current task state

-- Agent memory schema
CREATE TABLE agent_memory (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    agent_id VARCHAR(255),
    user_id BIGINT,
    memory_type ENUM('episodic', 'semantic', 'working'),
    content TEXT,
    embedding VECTOR(1536),
    importance_score FLOAT,
    created_at TIMESTAMP,
    accessed_count INT DEFAULT 0,
    last_accessed TIMESTAMP,
    VECTOR INDEX idx_memory_embedding (embedding),
    INDEX idx_agent_user (agent_id, user_id)
);

-- Retrieve relevant memories for context
SELECT content, memory_type, importance_score
FROM agent_memory
WHERE agent_id = :agent_id 
  AND user_id = :user_id
  AND (
    -- Semantic search for relevant context
    VEC_COSINE_DISTANCE(embedding, :current_context_embedding) < 0.3
    OR 
    -- Recent working memory
    (memory_type = 'working' AND created_at > NOW() - INTERVAL 1 HOUR)
  )
ORDER BY importance_score DESC, created_at DESC
LIMIT 20;

As agents interact with thousands of users over months, memory tables grow large. TiDB's horizontal scaling ensures performance remains consistent.

Real-Time Feature Stores for ML

Training and serving ML models requires consistent features across environments. TiDB can serve as a unified feature store:

-- User features for a recommendation model
CREATE TABLE user_features (
    user_id BIGINT PRIMARY KEY,
    embedding VECTOR(128),
    total_purchases INT,
    avg_order_value DECIMAL(10,2),
    category_preferences JSON,
    last_purchase_date TIMESTAMP,
    churn_risk_score FLOAT,
    updated_at TIMESTAMP
);

-- Batch feature computation (training)
INSERT INTO user_features 
SELECT 
    user_id,
    -- Aggregate features from transaction history
    -- (runs on TiFlash for analytical performance)
FROM transactions
GROUP BY user_id;

-- Point lookup for inference (serving)
SELECT embedding, total_purchases, avg_order_value, category_preferences
FROM user_features
WHERE user_id = :user_id;

The HTAP architecture means batch feature computation (analytical) and real-time serving (transactional) use the same database without contention.

Multimodal AI Applications

Modern AI apps process text, images, audio, and video. Embeddings from different modalities need to coexist:

CREATE TABLE media_library (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    media_type ENUM('text', 'image', 'audio', 'video'),
    content_url VARCHAR(1000),
    text_embedding VECTOR(1536),      -- CLIP text encoder
    image_embedding VECTOR(512),      -- CLIP image encoder
    audio_embedding VECTOR(768),      -- Wav2Vec
    metadata JSON,
    tags VARCHAR(500),
    created_at TIMESTAMP,
    VECTOR INDEX idx_text (text_embedding),
    VECTOR INDEX idx_image (image_embedding),
    VECTOR INDEX idx_audio (audio_embedding)
);

-- Cross-modal search: find images similar to text query
SELECT id, content_url, metadata,
       VEC_COSINE_DISTANCE(image_embedding, :text_query_embedding) AS similarity
FROM media_library
WHERE media_type = 'image'
  AND tags LIKE '%product%'
ORDER BY similarity ASC
LIMIT 20;

Managing multiple vector indexes for different modalities in separate databases becomes cumbersome quickly. TiDB consolidates this complexity.

TiDB Works at Any Scale

One common misconception is that distributed databases are "overkill" for smaller projects. Here's the reality: TiDB scales down as well as it scales up.

For Small Projects and Startups:

Start with a single-node TiDB Cloud Starter cluster (free tier available)
MySQL compatibility means your existing skills and tools work immediately
No upfront complexity - you write standard SQL
When you grow, scaling is just adding nodes - no application rewrites

For Growing Applications:

Seamless transition from prototype to production
No "rewrite day" when you outgrow your database
The same codebase works at 100 users or 100 million users

For Enterprise Scale:

Multi-region deployments with strong consistency
Handles petabyte-scale datasets
HTAP means no separate analytics infrastructure

The beauty is that you don't choose between "simple database for MVP" vs. "complex distributed system for scale." You get both. Start simple, scale when needed, never rewrite.

Vector Search Performance

TiDB's vector index performance depends on dataset size and configuration:

-- Create optimized vector index
CREATE VECTOR INDEX idx_embedding ON foo ((VEC_COSINE_DISTANCE(embedding))) USING HNSW;
ALTER TABLE foo ADD VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding))) USING HNSW;

Operational Benefits

Simplified Stack

Instead of managing:

Pinecone (vector search)
PostgreSQL (relational data)
Airflow + dbt (ETL pipelines)
Redis (caching)

You operate:

TiDB (handles all of the above)

This reduces:

Synchronization bugs: No eventual consistency issues between systems
Operational overhead: One database to monitor, backup, scale
Cost: Consolidated infrastructure, no data transfer fees between services

MySQL Ecosystem Compatibility

Your team's existing MySQL knowledge transfers directly:

# Standard MySQL drivers work
import mysql.connector

conn = mysql.connector.connect(
    host='tidb.cluster.example.com',
    port=4000,
    user='root',
    password='your_password',
    database='ai_app'
)

cursor = conn.cursor()
cursor.execute("""
    SELECT id, content, 
           VEC_COSINE_DISTANCE(embedding, %s) AS score
    FROM documents
    ORDER BY score ASC
    LIMIT 10
""", (query_embedding,))

ORMs like SQLAlchemy, Django ORM, and Prisma work without modification. This lowers the learning curve significantly.

Getting Started with PyTiDB: The Modern Way

While you can use TiDB with any MySQL-compatible driver, the PyTiDB SDK makes building AI applications significantly easier. It handles embedding generation, automatic vectorization, and provides a clean ORM-style interface.

Installation

pip install pytidb

# Optional: include built-in embedding models
pip install "pytidb[models]"

Quick Start: Building a RAG Application

Here's a complete RAG implementation using PyTiDB's auto-embedding features:

import os
from pytidb import TiDBClient
from pytidb.schema import TableModel, Field, FullTextField
from pytidb.embeddings import EmbeddingFunction

# Connect to TiDB
tidb_client = TiDBClient.connect(
    host=os.getenv("TIDB_HOST"),
    port=int(os.getenv("TIDB_PORT")),
    username=os.getenv("TIDB_USERNAME"),
    password=os.getenv("TIDB_PASSWORD"),
    database=os.getenv("TIDB_DATABASE"),
)

# Configure embedding provider (supports OpenAI, JinaAI, etc.)
tidb_client.configure_embedding_provider(
    "openai",
    api_key=os.getenv("OPENAI_API_KEY")
)

# Define your schema with auto-embedding
class Document(TableModel):
    __tablename__ = "documents"

    id: int = Field(primary_key=True)
    content: str = FullTextField()  # Full-text searchable

    # Auto-embeds the 'content' field using OpenAI
    content_vec: list[float] = EmbeddingFunction(
        "openai/text-embedding-3-small"
    ).VectorField(source_field="content")

    category: str = Field(max_length=100)
    created_at: str = Field()

# Create table
table = tidb_client.create_table(schema=Document, if_exists="skip")

# Insert documents - embeddings generated automatically!
table.bulk_insert([
    Document(
        id=1,
        content="TiDB supports HTAP workloads with TiFlash for real-time analytics.",
        category="features",
        created_at="2024-01-15"
    ),
    Document(
        id=2,
        content="PyTiDB is the official Python SDK for building AI apps with TiDB.",
        category="tools",
        created_at="2024-02-01"
    ),
    Document(
        id=3,
        content="Vector search in TiDB enables semantic similarity queries at scale.",
        category="features",
        created_at="2024-02-10"
    ),
])

# Semantic search - query is auto-embedded too!
results = (
    table.search("Python library for AI applications")
    .limit(3)
    .to_list()
)

for doc in results:
    print(f"Score: {doc['_score']:.3f}")
    print(f"Content: {doc['content']}")
    print(f"Category: {doc['category']}\n")

Output:

Score: 0.892
Content: PyTiDB is the official Python SDK for building AI apps with TiDB.
Category: tools

Score: 0.756
Content: Vector search in TiDB enables semantic similarity queries at scale.
Category: features

Score: 0.623
Content: TiDB supports HTAP workloads with TiFlash for real-time analytics.
Category: features

Hybrid Search: Combining Semantic and Keyword Search

PyTiDB supports hybrid search out of the box - combining vector similarity with full-text matching:

# Hybrid search: semantic + keyword matching
results = (
    table.search(
        "database for AI",
        search_type="hybrid"  # Combines vector + full-text
    )
    .limit(5)
    .to_pandas()  # Returns pandas DataFrame
)

print(results[['content', '_score', '_distance']])

Hybrid search delivers more accurate results by combining semantic understanding (vector search) with exact-term matching (full-text search).

Advanced Filtering with Vector Search

One of PyTiDB's strengths is combining vector search with SQL-style filtering:

from pytidb.sql import and_, or_

# Find semantically similar docs, but only from specific categories
results = (
    table.search("analytics and real-time processing")
    .filter(
        and_(
            Document.category == "features",
            Document.created_at > "2024-01-01"
        )
    )
    .distance_threshold(0.8)  # Only results with >0.8 similarity
    .limit(5)
    .to_list()
)

Image Search with Multi-Modal Embeddings

PyTiDB also supports multi-modal embeddings for image search:

from PIL import Image
from pytidb.embeddings import EmbeddingFunction

# Multi-modal embedding model (handles both text and images)
jina_embed = EmbeddingFunction("jina_ai/jina-embeddings-v4")

class Product(TableModel):
    __tablename__ = "products"

    id: int = Field(primary_key=True)
    name: str = Field()
    image_path: str = Field()

    # Automatically embeds images from the image_path
    image_vec: list[float] = jina_embed.VectorField(
        source_field="image_path",
        source_type="image"
    )

table = tidb_client.create_table(schema=Product, if_exists="skip")

# Insert products with images
table.insert(Product(
    id=1,
    name="Blue Sneakers",
    image_path="products/sneakers_blue.jpg"
))

# Search using natural language
results = table.search("running shoes").limit(5).to_list()

# Or search using another image
query_image = Image.open("query_shoe.jpg")
results = table.search(query_image).limit(5).to_list()

Why PyTiDB Simplifies Development

Compare this to the traditional approach:

Without PyTiDB:

Manually call OpenAI API to generate embeddings
Write raw SQL to create tables with VECTOR columns
Handle embedding generation for every insert
Write complex SQL queries for vector search
Manually combine results with metadata

With PyTiDB:

Define your schema with TableModel
Mark fields for auto-embedding
Insert data - embeddings happen automatically
Search with .search() - query embedding automatic
Filter and combine with SQL-like syntax

The SDK handles all the embedding plumbing, letting you focus on your application logic.

The Path Forward

Three years ago, vector databases as we know them today didn't really exist. Now they're everywhere. The stack is still figuring itself out - what used to require three different databases might soon need just one. Or maybe five specialized ones will win. Nobody knows for sure yet.

What's clear is that building AI applications at any meaningful scale means dealing with both structured and unstructured data, both transactions and analytics. You can stitch together multiple systems and deal with the synchronization headaches, or you can use something that handles it all in one place.

TiDB makes that bet: that consolidation beats fragmentation. That a single, scalable database beats orchestrating multiple specialized ones. For applications that need structured data and vector search, transactional consistency and analytical insights, that bet is looking pretty good.

Yes, distributed databases have complexity. But when the alternative is keeping three databases in sync while your app is down because of a race condition between systems, that complexity starts looking reasonable.

Try TiDB for Your AI Application

Ready to consolidate your AI data stack?

Get started:

TiDB Cloud: Sign up for a free cluster (no credit card required)
Documentation: Vector Search Guide
Example Projects: AI Application Templates on GitHub

Next steps:

Migrate your vector data from Pinecone/Weaviate to TiDB
Consolidate your feature store and transactional database
Build a RAG application using the example above
Join the TiDB Community Discord to share your experience

The AI era demands databases that can keep up. TiDB is ready.

Have you built AI applications on TiDB? Share your experience in the comments or reach out on Twitter/X @PingCAP.

If you find this article useful, share it and give me a follow on Twitter/X @codewithveek

Understanding TOCTOU: The Race Condition Hiding in Your Code

Victory Lucky — Sun, 15 Feb 2026 13:30:45 +0000

Time-of-Check to Time-of-Use (TOCTOU) is one of those sneaky vulnerabilities that can slip past even experienced developers. It's a race condition that occurs when there's a time gap between checking a condition and acting on it, and in that gap, everything can change.

What is TOCTOU?

TOCTOU vulnerabilities arise from a simple but critical assumption: that the state you just checked will remain the same when you use it. Unfortunately, in concurrent systems, this assumption is often wrong.

The pattern looks like this:

Time of Check: Your code verifies a condition (file exists, user has permission, resource is available)
Time Gap: A brief window where other processes can execute
Time of Use: Your code acts based on the earlier check
Problem: The condition has changed, but your code doesn't know it

Example 1: File System Race Conditions

The classic TOCTOU example involves file operations:

import { existsSync, readFileSync } from 'fs';

// ❌ VULNERABLE: TOCTOU race condition
function readUserFile(filename: string): string {
  // Time of Check
  if (existsSync(filename)) {
    // Time gap - another process could:
    // - Delete the file
    // - Replace it with a symlink to /etc/passwd
    // - Change its permissions

    // Time of Use
    const data = readFileSync(filename, 'utf-8');
    return data;
  }
  throw new Error('File not found');
}

Between the check and the read, an attacker (or even just another legitimate process) could manipulate the file system. This could lead to:

Reading sensitive files via symlink attacks
Privilege escalation in setuid programs
Data corruption or application crashes

The Fix: Use Atomic Operations

import { readFileSync } from 'fs';

// ✅ BETTER: Handle errors, don't separate check from use
function readUserFile(filename: string): string {
  try {
    // Check and use happen atomically in the OS
    return readFileSync(filename, 'utf-8');
  } catch (error) {
    if (error.code === 'ENOENT') {
      throw new Error('File not found');
    }
    throw error;
  }
}

The key insight: Let the operating system handle the check and use atomically. Don't try to do it yourself.

Example 2: Shared Singleton State in HTTP Handlers

A more subtle TOCTOU bug appears in web applications with shared state. Consider this Next.js authentication helper:

// ❌ VULNERABLE: Shared HttpClient singleton
const http = new HttpClient();

export const authenticatedHttp = async (...) => {
  const accessToken = await getAccessToken();
  http.setToken(accessToken);  // mutates shared instance!
  http.setUrl = baseUrl || "";  // mutates shared instance!
  return http;
};

In this example, a single HttpClient instance is shared across all requests. Under concurrent requests (which is normal in Next.js):

Request A calls authenticatedHttp() and sets its token
Request B calls authenticatedHttp() and overwrites the token
Request A uses the client, but now has Request B's token

This is a classic TOCTOU bug:

Time of Check: Request A sets its authentication token
Time of Use: Request A makes HTTP calls with the client
Problem: Between setting and using, Request B modified the shared state

The Real-World Impact

This vulnerability can cause:

User A accidentally authenticating as User B
Sensitive data leaking to the wrong user
Authorization bypasses
Difficult-to-reproduce bugs that only appear under load

The Fix: Avoid Shared Mutable State

// ✅ BETTER: Create a new instance per request
export const authenticatedHttp = async (...) => {
  const accessToken = await getAccessToken();
  const http = new HttpClient();  // new instance!
  http.setToken(accessToken);
  http.setUrl = baseUrl || "";
  return http;
};

Or even better, use immutable configuration:

// ✅ BEST: Immutable configuration
export const authenticatedHttp = async (...) => {
  const accessToken = await getAccessToken();
  return new HttpClient({
    token: accessToken,
    baseUrl: baseUrl || ""
  });
};

Common TOCTOU Scenarios

TOCTOU bugs appear in many contexts:

File System Operations

Checking file existence then opening it
Verifying permissions then accessing the file
Checking disk space then writing data

Authentication & Authorization

Validating a token then using it
Checking permissions then performing an action
Verifying session state then accessing resources

Resource Management

Checking availability then allocating
Validating constraints then modifying state
Testing conditions then acting on them

Shared State in Web Applications

Singleton services with mutable state
Global configuration objects
Shared database connections with session state

How to Prevent TOCTOU Vulnerabilities

1. Use Atomic Operations

Whenever possible, combine check and use into a single atomic operation:

// ❌ BAD: Separate check and use
if (canAccessResource(user, resource)) {
  accessResource(resource);
}

// ✅ GOOD: Single operation that checks and acts
accessResourceIfAuthorized(user, resource);

2. Avoid Shared Mutable State

Create new instances instead of reusing mutable ones:

// ❌ BAD: Shared mutable client
const sharedClient = new ApiClient();
sharedClient.setAuth(token);

// ✅ GOOD: New instance per request
const client = new ApiClient({ auth: token });

3. Use Proper Locking

When shared state is unavoidable, use locks or mutexes:

import { Mutex } from 'async-mutex';

const mutex = new Mutex();
const sharedResource = { value: 0 };

async function safeUpdate() {
  const release = await mutex.acquire();
  try {
    // Critical section - check and use are protected
    if (sharedResource.value < 100) {
      sharedResource.value++;
    }
  } finally {
    release();
  }
}

4. Design for Concurrency

Think about concurrent access from the start:

Use immutable data structures
Prefer functional programming patterns
Minimize shared state
Use message passing instead of shared memory

5. Handle Errors Gracefully

Don't assume checks guarantee success:

// ✅ GOOD: Handle the race condition gracefully
try {
  const data = await readFile(filename);
  return data;
} catch (error) {
  if (error.code === 'ENOENT') {
    // File disappeared between existence check and read
    logger.warn('File vanished during read', { filename });
    return null;
  }
  throw error;
}

Testing for TOCTOU Bugs

TOCTOU bugs are notoriously hard to test because they depend on timing:

Stress testing: Run concurrent operations to expose race conditions
Chaos engineering: Introduce random delays to widen the time gap
Static analysis: Use tools to detect check/use patterns
Code review: Look for shared mutable state and separate check/use operations

// Test helper to expose race conditions
async function concurrentTest(operation: () => Promise<void>, count: number) {
  const promises = Array(count).fill(null).map(() => operation());
  await Promise.all(promises);
}

// Use it to find bugs
await concurrentTest(async () => {
  await authenticatedHttp(); // Does this cause issues?
}, 100);

Conclusion

TOCTOU vulnerabilities remind us that in concurrent systems, the state we checked a moment ago might already be obsolete. The solution isn't to check faster—it's to design systems that don't rely on assumptions about state persistence across time gaps.

Key takeaways:

Combine check and use into atomic operations whenever possible
Avoid shared mutable state in concurrent contexts
Use proper synchronization when sharing is unavoidable
Design with concurrency in mind from the start
Handle race conditions gracefully when they occur

Remember: Between the time you check and the time you use, the world can change. Code accordingly.

Your Phone Is Stealing Your Life: Here's How to Take It Back

Victory Lucky — Thu, 22 Jan 2026 02:49:13 +0000

You're getting robbed every single day.
Not by some stranger on the street. By the device in your pocket that you check 150 times a day without even realizing it.
Your phone is stealing your attention. And attention isn't just some abstract thing. It's your life. It's the raw material of everything you could build, create, or become. When your attention gets hijacked, your life gets hijacked.

You already know this. You feel it every time you pick up your phone to check one thing, and somehow 45 minutes disappear. You feel it when you can't read a book for more than 10 minutes without getting antsy. You feel it when you're with people you care about, but your mind is somewhere else.

This isn't about becoming some tech-hating monk. I'm not telling you to delete everything and live in the woods. Technology is powerful. The internet is incredible. But the way you're using it right now is destroying your brain.
Here's how to fix it.

I. The Addiction You Won't Admit

Let's start with the truth you've been avoiding: you're addicted to your phone.
Not "I really like my phone" or "I use it a lot." Addicted. As in, you have a genuine behavioral addiction that shares more in common with gambling addiction than you'd like to admit.
How do I know? Try this experiment: put your phone in a drawer for 2 hours. Don't check it. Don't peek. Just 2 hours.
If the thought of that makes you anxious, if you're already thinking of reasons why you can't do it, if you're planning to cheat by checking "just once" for important messages; congratulations, you're addicted.

But here's what makes phone addiction especially insidious: it's socially acceptable. Nobody intervenes in your scrolling on Instagram. Nobody holds a family meeting because you check Twitter 80 times a day.
In fact, everyone else is doing it too, so it seems normal. It's not normal. It's mass hypnosis.

Your phone is designed to be addictive. Literally designed by teams of engineers whose job is to keep you hooked. They use the same psychological tricks that casinos use: variable rewards, infinite scroll, notifications, streaks, and likes.
Every time you pull down to refresh, you're pulling a slot machine lever. Sometimes you win (new likes, interesting content, a message from someone). Most times you don't. But the possibility of winning keeps you pulling.

The variable reward schedule is the most addictive pattern known to psychology. And it's baked into every app on your phone.
You're not weak. You're not undisciplined. You're fighting a billion-dollar industry that's spent decades perfecting the art of stealing your attention.
But you can still win.

II. What You're Really Scrolling Away From

Here's the question nobody wants to answer: what are you avoiding?
Because that's what scrolling really is. Avoidance. Every time you pick up your phone out of boredom, you're running from something.
Sometimes it's obvious. You're avoiding a difficult work task. You're avoiding an uncomfortable conversation. You're avoiding the fact that you're not where you want to be in life.

But most of the time, it's subtler. You're avoiding silence. You're avoiding being alone with your thoughts. You're avoiding the slight discomfort of not being stimulated for 30 seconds.
Your brain has learned that any moment of boredom, any hint of discomfort, any second of unstimulated existence can be immediately solved by checking your phone.

Waiting in line? Phone. Red light? Phone. Commercial break? Phone. Elevator? Phone. Walking from your car to the building? Phone.
You've trained yourself to never, ever be bored. And in doing so, you've destroyed your ability to think.
Because thinking requires boredom. Creativity requires boredom. Insight requires boredom. All the best ideas you've ever had came during moments of doing nothing; in the shower, on a walk, staring out a window.

But you don't have those moments anymore. You've optimized them away in favor of consuming other people's thoughts, other people's lives, other people's highlight reels.
You're so busy consuming that you've forgotten how to create. So busy scrolling that you've forgotten how to think.
And the worst part? You're avoiding the very things that would actually improve your life. The difficult project. The hard conversation. The uncomfortable truth about where you're headed.
Instead, you scroll. And scroll. And scroll. And wonder why nothing changes.

III. The Focus You Lost (And How to Get It Back)

Remember when you could read a book for hours? Watch a full movie without checking your phone? Have a conversation without your mind wandering?
Yeah, me neither. Or at least, not easily.
Your phone hasn't just stolen your time. It's stolen your ability to focus. And focus is the most valuable skill in the modern economy.

Deep work, the ability to concentrate without distraction on a cognitively demanding task, is becoming rarer while simultaneously becoming more valuable. The people who can still do it are winning. Everyone else is scrolling.
Here's what happened to your brain: you've trained it to expect a dopamine hit every few minutes. A notification. A new post. A text. Something.

Now, when you try to focus on something that doesn't provide that constant stimulation, reading, writing, thinking, or building, your brain freaks out. It feels wrong. It feels boring. It feels like you're missing something.
So you check. Just for a second. Just to see if anything happened. And then you're gone for 20 minutes, and you've forgotten what you were even working on.

This is called "context switching," and it's murdering your productivity. Every time you switch from focused work to checking your phone, it takes an average of 23 minutes to get back into deep focus.
Most people never get there at all. They're constantly switching, constantly distracted, constantly doing shallow work that feels busy but accomplishes nothing.
If you want to build anything meaningful, a business, a skill, a body of work, you need to get your focus back.
Here's how:

Start with the morning. Your morning sets the tone for your entire day. If you grab your phone within the first hour of waking up, you've already lost. You've handed control to the algorithm. You've trained your brain to expect stimulation before you've even brushed your teeth.

Instead: no phone for the first hour. None. Not even "just to check the weather." Get a separate alarm clock if you need to. This one change will transform your days.
Create phone-free zones. Your bedroom should be phone-free. Your meals should be phone-free. Your focused work time should be phone-free. Not on silent. Not face down. In another room.
Use time blocks. Work in 90-minute blocks of complete focus. No phone. No internet (unless required for the work). No distractions. Just you and the work. Take a break, then do it again.
Your focus is a muscle. It's atrophied from lack of use. But you can rebuild it. It just takes consistent practice.

IV. The Comparison Trap That's Killing You

Social media is a highlight reel. You know this. Everyone knows this. But you still can't help comparing your behind-the-scenes to everyone else's edited, filtered, carefully curated highlight reel.
You scroll through Instagram and see people with better bodies, better relationships, better lives. You scroll through LinkedIn and see people with better jobs, better success, better achievements. You scroll through Twitter and see people with better thoughts, better insights, better wit.
And slowly, subtly, it destroys you.
Because comparison is the thief of joy. And social media is comparison on steroids.

Here's what your brain doesn't understand: the people you're comparing yourself to are also comparing themselves to others. Everyone is looking at everyone else's highlight reel and feeling inadequate.

Nobody posts their failures. Nobody posts their struggles. Nobody posts the boring Tuesday where nothing interesting happened.
So you're comparing your full reality, the good, the bad, the boring, to everyone else's carefully selected best moments.
You can't win this game. It's rigged.
But here's what's even worse: while you're scrolling and comparing, you're not building. You're consuming other people's lives instead of living your own.

Every minute you spend watching someone else's vacation is a minute you're not planning your own. Every minute you spend admiring someone else's business is a minute you're not building yours. Every minute you spend envying someone else's relationship is a minute you're not investing in yours.
You're outsourcing your self-worth to strangers on the internet. People who don't know you. People who don't care about you. People who are playing the same game and feeling just as empty.
Stop playing. The only person you should compare yourself to is who you were yesterday. That's it.

V. The System That Actually Works

Okay, enough diagnosis. Here's the cure. Here's the system I've used and seen work for hundreds of people who were just as addicted as you are.

Step 1: The Audit
Track your screen time for one week without changing anything. Don't lie to yourself. Just observe. Most phones have built-in screen time tracking. Use it.
At the end of the week, look at the numbers. Really look at them. If you spent 4 hours a day on your phone, that's 28 hours a week. That's 1,456 hours a year. That's 60 full days.
You just spent 2 months of your life scrolling. How does that feel?

Step 2: The Purge
Delete the apps that are stealing your life. Not all of them. The ones you know are the problem.
For most people, that's social media. Instagram, TikTok, Twitter, Facebook. Delete them from your phone. Not "I'll just use them less." Delete them.
If you need them for work, access them on your computer during specific times. But get them off your phone.
You can always reinstall them later. But I'm betting you won't want to.

Step 3: The Replacement
Here's the key: you can't just remove a habit. You have to replace it.
Every time you feel the urge to scroll, you need something else to do. Have a book ready. Have a notebook ready. Have a project ready.
When you're waiting in line, read a page. When you're bored, think. When you have 10 free minutes, work on something that matters instead of consuming something that doesn't.
The urge to scroll will come. Don't fight it with willpower. Replace it with something better.

Step 4: The Barriers
Make it harder to waste time. Delete apps. Log out of websites. Put your phone in another room when you work. Use website blockers. Turn off all notifications except calls from actual humans.
Every barrier you create gives your future self a chance to make a better choice. You're not fighting yourself. You're designing an environment that makes good choices easier.

Step 5: The Schedule
Decide when you're allowed to check certain things. Email twice a day. Social media (if you must) once a day for 20 minutes. News once a day.
Everything else is off limits. Not "I'll try to limit it." Off limits. Like it doesn't exist.
This isn't about being perfect. It's about being intentional. It's about controlling your attention instead of letting it be controlled.

VI. What You Get Back

Here's what happens when you actually do this:
Your focus comes back. You can read again. You can think again. You can work on something for hours without checking your phone.
Your anxiety drops. You stop comparing. You stop worrying about what everyone else is doing. You stop feeling like you're missing out.
Your relationships improve. You're actually present with people. You have conversations without your phone on the table. You remember what people said because you were actually listening.
Your creativity returns. Ideas come back. Insights emerge. You start building instead of consuming.
Your time multiplies. Those 4 hours a day you were scrolling? That's 28 hours a week to read, learn, create, build, exercise, connect, and rest.
You get your life back.

Not all at once. Not dramatically. But slowly, steadily, undeniably.
The first few days are hard. Really hard. You'll feel anxious. You'll feel like you're missing something. You'll want to check.
That's withdrawal. That's your addiction protesting. Push through it.
After a week, it gets easier. After two weeks, you'll wonder why you waited so long. After a month, you won't recognize your old life.

VII. The Hard Truth

Here's what I need you to understand: this problem doesn't fix itself. It gets worse.
The apps are getting better at hooking you. The algorithms are getting smarter. The dopamine hits are getting more refined.
Every day you wait is another day of your life stolen. Another day of focus destroyed. Another day of potential wasted.
And you can't get those days back.

I'm not trying to scare you. I'm trying to wake you up. Because most people sleepwalk through this. They know their phone is a problem. They know they should cut back. They know they're wasting their life.
But they don't change. They just keep scrolling. And scrolling. And scrolling.
Until years pass and they look back and realize they can't account for where the time went. It just... disappeared. Into the infinite scroll.
Don't let that be you.
You have one life. One finite amount of time and attention. You can spend it consuming other people's thoughts and lives, or you can spend it building your own.

You can let the algorithm decide what you think about, or you can decide for yourself.
You can stay addicted, or you can break free.
The choice is yours. But you have to make it. And you have to make it now.
Because every moment you wait is another moment stolen. Another notification. Another scroll. Another piece of your life that you'll never get back.
Put the phone down. Take your life back. Start today.
Not tomorrow. Not Monday. Today.
Your future self will thank you.

The 24-Hour Challenge:

After reading this, put your phone in a drawer for 24 hours. Just try it. See what happens. See what you notice. See what you feel.
If you can't do 24 hours, you're more addicted than you think.
And that's exactly why you need to do it.

The Architecture of Self: Why You Keep Building the Wrong Life

Victory Lucky — Wed, 21 Jan 2026 12:28:56 +0000

You're building something every single day. A life. A self. A future version of you that will either thank you or resent you for the choices you're making right now.

But here's what nobody wants to admit: most people are terrible architects of their own lives. They build without blueprints, without vision, without any real understanding of what they're constructing. And then they wonder why everything feels unstable, why nothing quite fits, why the whole structure threatens to collapse every time the wind picks up.

I'm not going to tell you to wake up at 5am, start a morning routine, or use a productivity app. You've heard all that before, and if it worked, you wouldn't be reading this.

Instead, I want to show you why you keep building the wrong life, how to tear down the faulty foundation, and how to reconstruct something that actually matches who you're meant to become.

This will take time to read. This will take longer to implement. But if you're serious about stopping the cycle of false starts and abandoned projects, if you're done pretending that discipline alone will save you, then keep reading.

I. The Blueprint You Inherited

Every building starts with a blueprint. Every life starts with one too, except you didn't draw yours.

Your parents did. Your teachers did. Your culture did. The media did. The internet did. You've been handed a pre-designed life plan, and like an obedient contractor, you've been building it without question.

Here's the blueprint most people follow:

Excel in school so you can get into a good college. Get into a good college so you can land a good job. Land a good job so you can afford a good life. Work for 40 years. Retire. Die.

Somewhere in there, you're supposed to get married, buy a house, have kids, and post about it all on social media to prove you're winning.

But ask yourself this: did you ever sit down and consciously choose this blueprint? Or did you just accept it as "the way things are done"?

Most people never question the blueprint. They just build. And then 10, 20, 30 years later, they look around at what they've constructed and realize it doesn't feel like home. It feels like a prison they built with their own hands.

The job that was supposed to provide security feels like slow death. The relationship that was supposed to complete you feels like a performance you're tired of rehearsing. The life that was supposed to make you happy feels like someone else's dream that you're living out.

And the worst part? You can't even complain about it without sounding ungrateful. You have everything you're supposed to want. The problem isn't that you failed to follow the blueprint. The problem is that you followed it too well.

II. Why You Can't Just "Fix" Your Life

When people realize they're building the wrong life, their first instinct is to fix it. Optimize it. Make it better.

They read self-help books. They hire coaches. They try new productivity systems. They set goals for the new year. They promise themselves that this time will be different.

But it never is. Because you can't fix a house that's built on the wrong foundation. You can renovate the kitchen, repaint the walls, and upgrade the furniture, but if the foundation is cracked, the whole thing will eventually crumble.

Here's what I mean: let's say you hate your job. It drains you. It bores you. It makes you feel like you're wasting your life. So you decide to fix it. You start looking for a new job. You update your resume. You practice your interview skills. You land something better.

And for a few months, it feels great. You feel like you've solved the problem. But slowly, inevitably, the same feelings creep back in. The new job starts to feel just like the old one. Different building, same prison.

Why? Because you didn't change the foundation. You just moved to a different location on the same blueprint.

The foundation is your operating system. It's the set of beliefs, assumptions, and values that determine how you see the world and what you consider possible. And if that foundation is built on someone else's blueprint, no amount of surface-level changes will make your life feel right.

You need to go deeper. You need to excavate. You need to dig down to the bedrock and examine what you've been building on.

III. The Three Layers of Construction

Your life is built in three layers, and most people only ever work on the top one.

Layer 1: Actions

This is what you do every day. Your habits, your routines, your behaviors. This is where most self-help focuses. Do more. Be more disciplined. Wake up earlier. Work harder.

Layer 2: Identity

This is who you think you are. The stories you tell yourself about yourself. "I'm not a morning person." "I'm not good with money." "I'm an introvert." These identity statements shape what feels natural to you.

Layer 3: Worldview

This is how you see reality itself. What you believe is possible, what you believe is valuable, what you believe is true. This is the deepest layer, and it determines everything above it.

Most people try to change Layer 1 without touching Layer 2 or 3. They try to force new behaviors while maintaining the same identity and worldview. And they wonder why it feels so hard, why they keep slipping back into old patterns.

Here's the truth: lasting change only happens when you work from the bottom up. When you change your worldview, your identity shifts naturally. When your identity shifts, your actions follow effortlessly.

But here's the problem: most people don't even know what their worldview is. They've never examined it. They've never questioned it. They just inherited it and assumed it was reality.

So let's examine it.

IV. The Worldview Audit

I want you to answer these questions honestly. Don't give me the answers you think you should give. Give me the answers that are actually true based on how you live, not how you wish you lived.

What is the purpose of life? Not the philosophical answer you'd give at a dinner party. The real answer based on how you actually spend your time and energy.

For most people, if we judge by their actions, the purpose of life is: avoid discomfort, maintain status, consume entertainment, and distract yourself from death.

Is that what you believe? Maybe not consciously. But does your behavior suggest otherwise?

Next question: What makes someone successful? Again, not the Instagram caption version. The real version.

For most people: someone is successful if they have a prestigious job, make good money, and appear to have their life together on social media.

Do you believe that? Or do you believe something else? And if you believe something else, why are you still chasing the markers of success you just said don't matter?

Last question: What are you capable of? What's actually possible for you?

Most people severely underestimate themselves because they've been told, directly or indirectly, that safety is more important than potential. That staying small is more acceptable than risking failure. That dreaming too big is setting yourself up for disappointment.

So they aim low. They play it safe. They build a small life and tell themselves it's realistic.

But here's what I've learned after working with hundreds of people who've completely transformed their lives: you are capable of far more than you think. The limiting factor isn't your potential. It's your worldview.

You don't need more discipline. You need a different operating system.

V. The Operating System Upgrade

Your mind runs on an operating system just like your computer does. And just like a computer, if you're running outdated software, nothing works quite right.

Most people are running on Operating System 1.0: Industrial Age Thinking.

This OS was designed for a world that no longer exists. A world where the path to success was predictable, where hard work at a single job led to security, where the same rules applied to everyone.

But we don't live in that world anymore. The old OS is incompatible with modern reality. Yet people keep trying to run new apps on old software and wonder why everything crashes.

Here's what the upgrade looks like:

OS 1.0: Scarcity mindset

There's only so much success to go around. If someone else wins, I lose. I need to hoard resources and guard my position.

OS 2.0: Abundance mindset

Value is created, not divided. Collaboration beats competition. There's more than enough for everyone who's willing to create it.

OS 1.0: Fixed identity

I am who I am. People don't change. I'm not the type of person who could do that.

OS 2.0: Fluid identity

I am who I choose to become. Change is the default state of existence. I can develop any skill or trait if I'm willing to put in the work.

OS 1.0: External validation

My worth comes from what others think of me. Success means impressing people. Failure means embarrassment.

OS 2.0: Internal validation

My worth is inherent and not dependent on external approval. Success means alignment with my values. Failure is feedback, not judgment.

OS 1.0: Time as enemy

I'm running out of time. I'm too old to start. I should have figured this out by now.

OS 2.0: Time as ally

I have exactly the right amount of time. Starting now is better than starting later. Every year of experience is an advantage.

OS 1.0: Security through stability

The goal is to find something safe and stick with it forever. Change is risky. Uncertainty is dangerous.

OS 2.0: Security through adaptability

The goal is to become someone who can thrive in any environment. Change is inevitable. Uncertainty is opportunity.

You can't run a 2.0 life on a 1.0 operating system. You'll keep crashing. You'll keep feeling stuck. You'll keep wondering why everyone else seems to be figuring it out while you're still struggling.

The upgrade isn't comfortable. Your old OS will fight it. It will tell you that the new way of thinking is risky, naive, unrealistic. That's just your old programming trying to protect itself.

But you don't need protection. You need evolution.

VI. The Identity Trap

Let me tell you about the most dangerous thing you'll ever say: "I am..."

Every time you complete that sentence, you're reinforcing a prison. You're telling your brain what's allowed and what's not. You're drawing boundaries around your potential.

"I am an introvert." So you avoid situations that could expand your social skills.

"I am not a creative person." So you never develop the creative muscles that everyone has.

"I am not good with money." So you perpetuate the exact patterns that keep you broke.

These identity statements feel true because you've been living them for years. They feel like facts about who you are. But they're not facts. They're choices. Old choices that you keep making unconsciously.

Here's how the identity trap works:

You try something once and fail. Based on that single data point, you create an identity statement: "I'm not good at X." That identity statement filters your perception. You stop noticing opportunities to improve at X. You avoid situations where X might be required. Your brain confirms your identity by finding evidence that supports it and ignoring evidence that contradicts it.

Years pass. The identity calcifies. It becomes part of your self-concept. And now, even thinking about challenging it feels like you'd be lying about who you are.

But here's the truth: you are not a fixed thing. You are a process. You are always becoming. And the question isn't "who am I?" but "who am I becoming?"

Every action you take is a vote for the identity you're building. Every time you go to the gym, you're voting for "I am someone who takes care of their body." Every time you skip it, you're voting for the opposite.

Neither vote makes you a bad person. But the votes add up. And eventually, they determine who you become.

So stop asking "Is this who I am?" Start asking "Is this who I want to become?"

Because the person you're building, consciously or not, is the person you'll have to live with for the rest of your life.

VII. The Pain You're Avoiding Is The Path You Need

There's a specific type of pain you've been running from your whole life. It's not physical pain. It's not even emotional pain in the traditional sense.

It's the pain of uncertainty. The pain of not knowing. The pain of stepping outside the script and writing your own story.

And until you face it, you'll keep building the wrong life.

Most people choose familiar suffering over unfamiliar possibility. They'd rather stay in a job they hate than face the uncertainty of starting something new. They'd rather maintain a relationship that's slowly dying than face the uncertainty of being alone. They'd rather keep living a small, safe life than face the uncertainty of pursuing something that actually excites them.

Why? Because familiar suffering is predictable. You know exactly how bad it will be. You've developed coping mechanisms. You've built a comfortable numbness around it.

But unfamiliar possibility? That's terrifying. Because you don't know how it will turn out. You might fail. You might look foolish. You might discover that you're not as capable as you thought.

So you avoid it. You find reasons why now isn't the right time. You convince yourself that you need to prepare more, learn more, be more ready.

But here's what you're really doing: you're trading your potential for certainty. You're choosing to know exactly how mediocre your life will be rather than risk discovering how extraordinary it could become.

And every year you make that trade, it gets harder to change. The familiar suffering becomes more familiar. The unfamiliar possibility becomes more unfamiliar. Until eventually, you can't even imagine a different life anymore.

This is how people end up at 40, 50, 60 years old, wondering where their life went. They spent it avoiding the very pain that would have set them free.

So let me ask you directly: what pain are you avoiding? What uncertainty are you running from? What possibility are you refusing to face?

Because that's exactly where you need to go.

VIII. The Future Self Exercise

Here's something I want you to try. It's going to feel strange, maybe even silly, but do it anyway.

Close your eyes and imagine yourself 10 years from now. Not the idealized version. Not the version where everything went perfectly. The version where you continued exactly as you are now for another decade.

Same patterns. Same choices. Same avoidance. Same fears. Same comfortable suffering.

What does that person look like? How do they carry themselves? What do they regret? What opportunities passed them by while they were playing it safe?

Now I want you to have a conversation with them. Let them tell you what it's like to be them. Let them tell you about the price they paid for your current choices.

Sit with that for a moment. Really feel it.

Now, imagine a different version of yourself 10 years from now. The version who started making different choices today. Who faced the uncertainty. Who stopped building someone else's life and started building their own.

What does that person look like? How do they carry themselves? What did they create? What did they become?

Have a conversation with this version too. Let them tell you what it's like to be them. Let them tell you about the path they took to get there.

Here's the critical insight: both of these people exist as possibilities right now. Both futures are available to you. The only difference is the choices you make between now and then.

Every day, with every choice, you're voting for one future or the other. You're building one version of yourself or the other.

Which one are you building?

IX. The Resistance Algorithm

Your brain is designed to keep you safe, not to help you grow. It's designed to avoid pain, not to pursue potential. And it's really, really good at its job.

Every time you try to make a significant change, your brain launches a sophisticated resistance algorithm. It generates thoughts that sound reasonable, responsible, and realistic. But they're really just sophisticated excuses.

Here are the most common outputs of the resistance algorithm:

"I'll start on Monday." Translation: I'm afraid to start now because then I'd have to actually commit, so I'm postponing the decision.

"I need to do more research first." Translation: I'm using the pursuit of information as a way to avoid the risk of action.

"This isn't the right time." Translation: There will never be a right time because the right time would require me to be someone I'm not yet, which is exactly who I'd become by starting now.

"I don't have enough money/time/resources." Translation: I'm waiting for perfect conditions that will never arrive instead of working with what I have.

"What if I fail?" Translation: I'm more committed to protecting my ego than to pursuing my potential.

"What will people think?" Translation: I'm letting the imagined judgments of others dictate my actual life choices.

The resistance algorithm is powerful because it doesn't feel like resistance. It feels like wisdom. It feels like rational thinking. It feels like you're being smart and careful.

But here's how to identify it: the resistance algorithm always argues for smallness. It always argues for safety. It always argues for waiting, preparing, and thinking more instead of doing.

And it never, ever argues for the thing that scares you most, which is usually the exact thing you need to do.

So when you notice these thoughts, don't argue with them. Don't try to prove them wrong. Just recognize them for what they are: your brain doing its job of keeping you safe.

Thank your brain for its concern. Then do the scary thing anyway.

X. The Minimum Viable Life

Here's a question that will change everything: what's the minimum viable version of the life you actually want?

Not the Instagram version. Not the version where everything is perfect and you've arrived. The minimum viable version. The simplest possible expression of the life that would make you feel alive.

Most people never build the life they want because they're aiming for the complete, perfect version right from the start. They want the successful business with a team and an office and all the trappings. They want the perfect relationship with someone who checks every box. They want the ideal body with six-pack abs and perfect muscle definition.

And when they can't achieve all of that immediately, they don't start at all.

But here's what successful people understand: everything starts as a minimum viable version. The business starts as a side project. The relationship starts as a conversation. The body transformation starts with a single workout.

You don't need to have it all figured out. You just need to build the smallest version that works, then iterate from there.

So what's your minimum viable life?

If you want to be a writer, you don't need to publish a bestselling book tomorrow. You need to write 200 words today.

If you want to start a business, you don't need a perfect business plan and funding. You need to solve one problem for one person.

If you want to transform your health, you don't need a complete overhaul. You need to make one better choice at your next meal.

The minimum viable version isn't sexy. It doesn't make for a good story. It won't impress anyone. But it has one critical advantage: you can start it today.

And once you start, once you prove to yourself that you can build even the smallest version of what you want, everything changes. You gain momentum. You gain confidence. You gain clarity about what comes next.

The life you want isn't built in one dramatic transformation. It's built in a thousand small iterations, each one slightly better than the last.

So stop waiting for perfect conditions. Start building the minimum viable version today.

XI. The Energy Audit

Here's something nobody talks about: you have a limited amount of energy, and where you invest it determines the quality of your life.

Every person, situation, habit, and commitment in your life either generates energy or drains it. And most people are running a massive energy deficit without even realizing it.

Think about your daily life. How much of your energy goes to:

Things you don't care about but feel obligated to do? People who drain you but you can't say no to? Habits that you mindlessly repeat despite knowing they make you feel worse? Worrying about things you can't control? Maintaining an image that isn't really you? Comparing yourself to others and feeling inadequate?

Now think about how much energy goes to:

Things that genuinely excite you? People who energize and inspire you? Habits that compound into a better life? Taking action on things you can control? Being authentic and letting go of pretense? Focusing on your own path and progress?

For most people, the ratio is wildly skewed toward energy-draining activities. And then they wonder why they're exhausted all the time, why they can't seem to make progress on what matters, why they feel like they're running on empty.

Here's the brutal truth: you will never build the life you want while giving your best energy to things you don't care about.

You need to do an energy audit. Go through everything in your life—every commitment, every relationship, every habit, every recurring activity—and ask: Does this give me energy or take it?

Then you need to make some hard decisions. You need to protect your energy like it's the most valuable resource you have, because it is.

This doesn't mean you become selfish or ruthless. It means you become intentional. It means you stop saying yes to everything out of obligation and start saying yes to things that align with the life you're building.

Every time you say yes to something that drains you, you're saying no to something that could energize you. Every time you spend an hour on something that doesn't matter, you're not spending that hour on something that does.

Your energy is finite. Your time is finite. Stop giving it away to things and people who don't deserve it.

XII. The Two-Year Window

If I told you that you could completely transform your life in two years, would you believe me?

Most people wouldn't. Two years doesn't sound like enough time for real transformation. Real change takes longer than that, right?

Wrong.

Two years is an enormous amount of time if you use it correctly. It's 730 days. 104 weeks. Countless hours that you can invest in becoming someone completely different.

Think about where you were two years ago. How different was your life? How different were you? Probably not that different, right?

Now imagine if you had spent those two years deliberately building toward a specific vision. Reading every day. Learning new skills. Building something meaningful. Surrounding yourself with people who elevated you.

Where would you be now? Who would you be now?

The tragedy is that two years is going to pass whether you use it intentionally or not. Two years from now, you'll be two years older. The only question is whether you'll also be two years better.

Here's what's possible in two years if you actually commit:

You can become fluent in a new language. You can build a six-figure business from scratch. You can completely transform your body. You can write a book. You can develop a valuable skill that opens new opportunities. You can build a network of extraordinary people. You can become someone you barely recognize.

But here's what it requires: you have to start now. You have to commit fully. You have to stop dabbling and start dedicating.

Most people waste two years because they spend it trying to keep all their options open. They work on their side project for a few hours a week while maintaining their comfortable job. They go to the gym occasionally while still eating poorly most of the time. They talk about making changes while continuing the same patterns.

And two years later, they've made marginal progress at best, often none at all.

But the people who actually transform their lives in two years? They close the other doors. They burn the ships. They go all in on becoming someone different.

They don't try to build a new life while maintaining the old one. They make a clean break and commit completely to the person they're becoming.

So here's my question: what could you become in two years if you actually committed? Not what you think is realistic. What's actually possible if you gave it everything you have?

And more importantly: why aren't you starting today?

XIII. The Architecture of Obsession

People talk about balance like it's a virtue. Work-life balance. Balanced approach. Everything in moderation.

But here's what nobody tells you: nothing great was ever built through balance.

Great things are built through obsession. Through imbalance. Through a willingness to go all-in on something that matters to you, even if it looks crazy to everyone else.

The problem is that most people are obsessed with the wrong things. They're obsessed with what other people think. They're obsessed with maintaining comfort. They're obsessed with avoiding failure.

These are destructive obsessions that keep you small and safe.

But there's another kind of obsession. A generative obsession. An obsession with building something meaningful, becoming someone capable, creating something that didn't exist before.

This kind of obsession doesn't feel like work. It feels like play. It feels like you can't not do it. It feels like everything else is a distraction from the thing that actually matters.

When you find this kind of obsession, everything changes. You don't need discipline because you're pulled toward it naturally. You don't need motivation because the work itself is energizing. You don't need to force yourself to stay focused because focus happens automatically.

But here's the catch: you can't manufacture this obsession. You can't fake it. You either feel it or you don't.

So the question becomes: what are you actually obsessed with? Not what you think you should be obsessed with. Not what looks impressive to others. What genuinely captures your attention and won't let go?

For most people, the answer is: nothing. They've never allowed themselves to become obsessed with anything because obsession seems irresponsible, unbalanced, risky.

So they dabble in everything and commit to nothing. They spread themselves thin across a dozen interests and wonder why nothing ever takes off.

But the people who build extraordinary lives? They give themselves permission to become obsessed. They find the thing that lights them up and they pursue it relentlessly, unapologetically, completely.

They structure their entire life around that obsession. They eliminate distractions. They say no to opportunities that don't serve it. They optimize everything for maximum progress on the thing that matters most.

This isn't balance. This is architecture. The deliberate construction of a life built around what you actually care about.

And it's the only way to build something that matters.

XIV. The Daily System

Here's where theory meets practice. Here's where philosophy becomes action.

You can have all the insights in the world, but without a daily system to implement them, you'll stay exactly where you are.

A daily system isn't a routine. Routines are about doing the same things at the same time every day. Systems are about creating conditions that make your desired outcomes inevitable.

Here's the system I want you to build:

Morning: Set The Frame

Before you check your phone, before you respond to anyone else's priorities, you need to set your own frame for the day.

Ask yourself: What would make today meaningful? Not productive. Not busy. Meaningful. What's the one thing that, if you accomplished it, would make you feel like you moved closer to who you're becoming?

Write it down. Make it your priority. Protect it fiercely.

Midday: Reality Check

At some point around midday, stop and assess. Are you actually doing the meaningful thing? Or have you gotten distracted by urgency, obligations, and other people's priorities?

If you've drifted, course correct. If you're on track, reinforce it.

This simple pause prevents you from sleepwalking through your day and wondering where the time went.

Evening: Integration

Before you go to bed, review the day. Not to judge yourself. Not to beat yourself up for what you didn't do. But to integrate what you learned.

What worked today? What didn't? What would you do differently tomorrow? What insight did you gain about yourself, your work, or your path?

Write it down. The act of writing forces clarity. The act of reviewing compounds learning.

This daily cycle—set the frame, reality check, integrate—creates a feedback loop that accelerates your growth exponentially.

But here's the key: you have to actually do it. Not when you feel like it. Not when you remember. Every single day.

Because the difference between the person you are and the person you're becoming is measured in daily systems, not occasional efforts.

XV. The Final Architecture

So here we are. You've read thousands of words about why you keep building the wrong life and how to build the right one.

Now comes the hardest part: actually doing it.

Most people will read this, feel inspired for a few days, then slowly drift back to their old patterns. They'll have some good insights, maybe make a few changes, but ultimately stay in the same basic structure they've been living in.

Don't be most people.

You now understand that you inherited a blueprint you never chose. You understand that fixing surface-level problems won't work if the foundation is wrong. You understand that your worldview, identity, and actions need to align. You understand that the pain you're avoiding is the path you need. You understand that time is both shorter and longer than you think.

The question is: what are you going to do with this understanding?

Here's what I recommend:

Block out a full day this week. Not a few hours. A full day. Use it to go through the excavation process. Really dig into what you want and what you don't want. Get brutally honest about where you are and where you're going.

Then make a decision. Not a wish. Not a hope. A decision.

Decide who you're becoming. Decide what you're building. Decide what you're willing to sacrifice and what you're not. Decide what gets your energy and what doesn't.

Then build the daily system that makes that decision inevitable.

Because here's the truth that nobody wants to hear: you already know what you need to do. You've known for a while. You're just afraid to do it.

Afraid of what it will cost. Afraid of who you'll have to become. Afraid of the uncertainty. Afraid of the judgment. Afraid of the possibility that you might actually succeed and have to live up to that new version of yourself.

But that fear is just your old operating system trying to keep you safe. It's just the old blueprint trying to maintain itself. It's just the resistance algorithm doing its job.

And you don't have to listen to it anymore.

You can thank it for its service and start building something new. Something that actually fits who you're meant to become. Something that makes you excited to wake up in the morning instead of hitting snooze and wishing for another life.

The architecture is simple:

Know what you don't want with brutal clarity. Know what you do want with courageous honesty. Build the identity that makes it natural. Create the daily system that makes it inevitable. Protect your energy like your life depends on it. Go all-in on what actually matters.

That's it. That's the whole thing.

Simple, but not easy. Because it requires you to stop building someone else's life and start building your own.

And that's the scariest, most liberating thing you'll ever do.

So here's my final question: are you ready to stop being a terrible architect of your own life?

Are you ready to tear down the faulty structure you've been maintaining and build something that actually deserves the time you're investing in it?

Are you ready to stop playing it safe and start playing to win?

Because two years from now, you're going to be somewhere. The only question is whether you'll be somewhere you chose or somewhere you defaulted to.

Start building.

Today.

How to Fix "Cannot Access '[variable]' Before Initialization" in Next.js

Victory Lucky — Tue, 22 Jul 2025 11:27:43 +0000

Recently, I was working on a project using Next.js with the App Router, and I encountered an error I had never seen before, even after years of working with Next.js. At first, I thought it was a simple issue. But after multiple attempts to fix it, the error persisted and ended up delaying our production deployment.

In this article, I’ll break down what causes the "Cannot access '[variable]' before initialization" error, where it typically shows up in Next.js, and how I finally resolved it.

What Causes This Error?

First, it's important to point out:

This is not a Next.js-specific error. It’s a JavaScript runtime error that typically shows up when you're dealing with ES module imports, especially when there's a circular dependency involved.

Basically, the error happens when one module tries to access a variable or function from another module before it’s finished initializing often due to circular imports.

Why This Error Is So Hard to Track

One of the most frustrating things about this error is that it doesn’t happen at build time. It shows up at runtime when everything’s already bundled and Next.js is collecting page data. In my case, the error wasn’t even pointing to anything obvious. It was buried somewhere inside the generated code, making it extremely difficult to figure out where the issue was actually coming from.

I even tried using madge to visualize circular imports:

npx madge --circular src/

But it didn’t detect any cycles - which honestly made things more frustrating.

The Setup That Caused It (My Case)

In my project, I had a schema-helper.ts file where I defined some shared columns and constants like:

// schema-helper.ts
export const id = varchar("id", { length: 36 })
  .primaryKey()
  .$defaultFn(() => generateUniqueId());

export const userId = varchar("user_id", { length: 36 })
  .notNull()
  .references(() => users.id, { onDelete: "cascade" });

export const createdAt = timestamp("created_at").defaultNow();
export const updatedAt = timestamp("updated_at").defaultNow().onUpdateNow();

export const postTypeEnum = ["general", "product", "service", "event"] as const;
export const postStatusEnum = [
  "draft",
  "published",
  "archived",
  "deleted",
] as const;

I was using these shared fields across different schema files:

// posts.ts
export const posts = mysqlTable("posts", {
  id,
  userId,
  type: mysqlEnum("type", postTypeEnum).notNull(),
  ...createdAt,
  updatedAt,
});

// medias.ts
export const medias = mysqlTable("media", {
  id,
  userId: userId,
  type: mysqlEnum("type", mediaType).notNull(),
  ...createdAt,
  updatedAt,
});

Seemed neat and DRY, right? But behind the scenes, userId was referencing the users table, and users.ts was indirectly importing one of the other schema files through a service or handler.

That’s how I ended up with a hidden circular import, and madge couldn’t catch it.

How I Finally Solved It

After hours of debugging and rethinking the structure, the solution turned out to be straightforward:

I moved the externally declared columns (like userId) out of the shared schema-helper.ts file, and defined them directly inside each schema file that used them.

So instead of this:

// ❌ in schema-helper.ts
export const userId = varchar("user_id", { length: 36 })
  .notNull()
  .references(() => users.id, { onDelete: "cascade" });

I did this:

// ✅ directly inside posts.ts
userId: varchar("user_id", { length: 36 })
  .notNull()
  .references(() => users.id, { onDelete: "cascade" });

I repeated that process for all my schema files (posts, media, likes, etc.), and once I got rid of the import loop, the error disappeared completely.

Final Thoughts

This bug was incredibly frustrating - not just because of the error itself, but because it didn’t surface in any obvious way. There were no TypeScript errors. No clear runtime stack trace. No helpful warning from the build system.

It’s one of those situations where your code is technically correct, but structurally flawed.

If you’re running into this error in your Next.js (or really, any Node/TypeScript) project, especially when using shared helpers or modularized schemas:

Look out for circular imports, even indirect ones
Avoid referencing entities from other modules inside shared files
Move dependent code closer to where it's used

And if all else fails, start simplifying the structure, even if it means a little duplication in the short term. It might just save your sanity.

Let me know if you want to dive deeper into this or need help untangling something similar in your project. I’ve been there.

And don't forget to follow me on X @CodeWithVick

The AI Paradox: Why I Use But Don't Trust Artificial Intelligence in 2025

Victory Lucky — Mon, 10 Mar 2025 16:50:54 +0000

It's the year 2025, and AI (Artificial Intelligence) has taken over the world, from Programming to Image/Video generation to helping automate some tedious tasks. However, it also poses some real threats, so in this post, I'm going to explain why AI is great and why I don't rely on it (at least for now).

The Good Side of Artificial Intelligence

Before we talk about the good side of Artificial Intelligence, let's talk a little about its history,

The term artificial intelligence was first coined by John McCarthy in 1956 when he held the first academic
conference on the subject. But the journey to understand if machines can truly think began much before that. In
Vannevar Bush’s seminal work As We May Think he proposed a system which amplifies people’s
knowledge and understanding. Five years later, Alan Turing wrote a paper on the notion of machines being able to
simulate human beings and the ability to do intelligent things, such as play Chess.

The above snippet was from History of AI

Now, let's talk about the good side of AI,
In recent times, Artificial Intelligence has been a very useful tool, it's being used to improve and automate different sectors including the health sector, Software programming, Image/Video generation, and so much more, and for programmers like me it has been greatly helpful in improving my productivity and helped me build apps faster.

I know you may wonder, why then do I say I don't trust AI? Well, I will explain that part, then maybe you will agree with me.

Why I don't trust AI

Artificial Intelligence has been a significant part of my productivity tools, but it has also been a major cause of my mental exhaustion, yes I mean that, you know despite how useful it has been to me, I have made sure to never rely solely on it because doing this leads to two(2) things,

Brain fatigue, and
Brain Laziness.

They sound familiar, right? Yeah, I know, but they're different.

What's the difference between Brain Fatigue and Brain Laziness?

Brain fatigue also known as mental fatigue or mental exhaustion, is a feeling of tiredness that occurs when your brain is overworked, while Brain Laziness or Mental Laziness is the art of intentionally avoiding activities that demand great use of the mind or that require deep thinking.

Now that you know what Brain fatigue and Brain Laziness are, let's talk about how they're caused by AI.

Before the breakthrough of Artificial intelligence in 2022 when ChatGPT was released, the traditional way of bootstrapping an idea was to either use a pen and paper to write down an outline for your idea or use a note app, but since the introduction of AI most people bootstrap their ideas through AI apps like ChatGPT and oftentimes they leave all the work for AI to do for them ( outlining, refining, etc.), I know you be thinking, "but that's not bad?" absolutely, it's not bad but the act of doing such is known as Brain Laziness which then leads to Brain fatigue, but how?

How does AI cause Brain Laziness and fatigue?

You see, in my experience, the human brain has a way that it works, which is that it is easier to resolve a problem you cause than one caused by another, and the process of trying to resolve this problem is where Brain fatigue occurs.

Let me show you an example.
The code below was written by an AI, and there's a bug in it.

Written by AI

 addAttributes() {
    return {
      ...this.parent?.(),
      level: {
        default: 1,
        parseHTML: (element) =>
          Number(element.tagName.replace("h", "")),
        renderHTML: (attributes) => ({
          level: attributes.level,
        }),
      },
    };
  },

Fixed by me

 addAttributes() {
    return {
      ...this.parent?.(),
      level: {
        default: 1,
        parseHTML: (element) =>
// the bug was the absence of `toLowerCase` 
          Number(element.tagName.toLowerCase().replace("h", "")),
        renderHTML: (attributes) => ({
          level: attributes.level,
        }),
      },
    };
  },

at first glance you will think they're the same, which was why discovering this bug took hours (after rewriting other parts of apps thinking they were the source of the bug) which caused me a Brain fatigue as I was tensed and overworked my brain trying to figure out the bug, mind you that if this was originally written by me, the probability of causing such a bug would've been significantly lower.

Conclusion

What am I trying to say here? The use of AI is good ( in fact, developers who don't use it might get overthrown by those who do), but over-reliance on it can be problematic, especially to your brain.

What do you think? Have you ever encountered such a situation before? Do let me know in the comments or on Twitter at CodewithVick

How to Fix the "Detected Multiple Renderers Concurrently Rendering the Same Context Provider" Warning in Next.js

Victory Lucky — Sat, 25 Jan 2025 22:17:44 +0000

Recently, I was working with Next.js (App Router) and I encountered this warning:

Warning: Detected multiple renderers concurrently rendering the same context provider. This is currently unsupported.

I was a bit confused as I had no idea what the actual cause was but after some research and trials, I found out the cause and was able to fix it, so in this post I will be sharing the possible cause, how to prevent it and how to fix the Detected multiple renderers concurrently rendering the same context provider. This is currently unsupported warning.

This warning typically appears when using Next.js App Router with both server and client components. Let's explore the causes and solutions to resolve it effectively.

Understanding the Warning

This warning occurs when React detects the same context provider being rendered by different rendering environments (server vs client) during hydration. This is common in Next.js applications that mix server and client components while using React Context.

Cross-Environment Rendering: When a context provider is rendered in both server and client environments (e.g., in a layout shared by both).
Improper Component Boundaries: Placing context providers in server components instead of client components.
Duplicate Providers: Accidentally rendering the same provider multiple times in the component tree.

In my case, the issue was caused by a custom hook (code below) for a context provider that was in a different file which led to duplicate rendering.

Before the fix

"use client";

import { createContext } from "react";
import { SiteSettings } from "../types";
import { DEFAULT_SETTINGS } from "../lib/settings/config";

export const SiteConfigContext = createContext<SiteSettings>(DEFAULT_SETTINGS);

export function SiteConfigProvider({
  children,
  initialConfig,
}: {
  children: React.ReactNode;
  initialConfig: SiteSettings;
}) {
  return (
    <SiteConfigContext.Provider
      value={{ ...DEFAULT_SETTINGS, ...initialConfig }}
    >
      {children}
    </SiteConfigContext.Provider>
  );
}

"use client";
import { useContext } from "react";
import { SiteConfigContext } from "../context/SiteConfig";

export const useSiteConfig = () => {
  const context = useContext(SiteConfigContext);

  if (!context) {
    throw new Error("useSiteConfig must be used within a SiteConfigProvider");
  }

  return context;
};

After the fix

"use client";

import { createContext } from "react";
import { SiteSettings } from "../types";
import { DEFAULT_SETTINGS } from "../lib/settings/config";

export const SiteConfigContext = createContext<SiteSettings>(DEFAULT_SETTINGS);

export function SiteConfigProvider({
  children,
  initialConfig,
}: {
  children: React.ReactNode;
  initialConfig: SiteSettings;
}) {
  return (
    <SiteConfigContext.Provider
      value={{ ...DEFAULT_SETTINGS, ...initialConfig }}
    >
      {children}
    </SiteConfigContext.Provider>
  );
}
import { useContext } from "react";

export const useSiteConfig = () => {
  const context = useContext(SiteConfigContext);

  if (!context) {
    throw new Error("useSiteConfig must be used within a SiteConfigProvider");
  }

  return context;
};

Combining the hook with the context provider resolved the issue because this now lets the provider be rendered once.

Other Ways to Fix the Error

1. Ensure Context Providers are Client Components

All context providers must be Client Components. Explicitly mark them with 'use client':

'use client'; // Essential for context providers

import { createContext, useContext } from 'react';

export const MyContext = createContext();

export function MyProvider({ children }) {
  return <MyContext.Provider value={/*...*/}>{children}</MyContext.Provider>;
}

2. Proper Provider Placement in Component Tree

Wrap your app with providers in a Client Component boundary. Never place providers in Server Components:

// app/providers.jsx
'use client';

import { MyProvider } from './my-context';

export function Providers({ children }) {
  return <MyProvider>{children}</MyProvider>;
}

// app/layout.jsx (Server Component)
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {/* Providers now only render on client */}
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

3. Avoid Duplicate Providers

Ensure providers aren't duplicated across layouts/pages. Check your component hierarchy using React DevTools.

4. Upgrade Dependencies

Some older versions have known issues. Update to at least:

Next.js 13.4+
React 18.2+

npm install next@latest react@latest react-dom@latest

Key Considerations for Next.js

Root Layout is a Server Component: Never place providers directly here without a Client Component wrapper
Third-Party Providers: Wrap them in your own Client Component:

   'use client';
   import { ThirdPartyProvider } from 'some-library';

   export function CustomProvider({ children }) {
     return <ThirdPartyProvider>{children}</ThirdPartyProvider>;
   }

Server-Side Data: Pass data from Server Components to Client Components via props:

   // app/page.jsx
   export default async function Page() {
     const data = await getData();
     return <ClientComponent data={data} />;
   }

Common Pitfalls to Avoid

❌ Mixing Providers in Server Components:

// app/layout.jsx
import { ClientProvider } from './client-provider';

export default function Layout({ children }) {
  // Will cause warning - layout is Server Component
  return (
    <html>
      <body>
        <ClientProvider>{children}</ClientProvider>
      </body>
    </html>
  );
}

✅ Correct Approach:

// app/providers.jsx
'use client';
export function AllProviders({ children }) {
  return (
    <Provider1>
      <Provider2>{children}</Provider2>
    </Provider1>
  );
}

// app/layout.jsx
import { AllProviders } from './providers';

export default function Layout({ children }) {
  return (
    <html>
      <body>
        <AllProviders>{children}</AllProviders>
      </body>
    </html>
  );
}

Summary

To resolve the multiple renderers warning:

Ensure all context providers are Client Components
Properly separate providers in Client Component boundaries
Avoid duplicate providers in the component tree
Keep dependencies updated

By following these steps, you'll be able to fix the "Detected multiple renderers concurrently rendering the same context provider. This is currently unsupported" warning.

If you found this tutorial helpful, feel free to share it with others. And don’t forget to follow me on Twitter for more web development tips and tutorials.

Happy coding! 🚀

Connect with Me

Portfolio: devvick.online
GitHub: github.com/lucky-victory
Twitter: @CodewithVick

How to Set Up a Next.js Project from Scratch

Victory Lucky — Sat, 25 Jan 2025 18:22:11 +0000

Next.js is a powerful React framework that makes it easy to build server-side rendered (SSR) and statically generated websites. Whether you’re building a blog, an e-commerce site, or a portfolio, Next.js has you covered. In this tutorial, we’ll walk through how to set up a Next.js project from scratch.

Step 1: Install Node.js

Before we start, make sure you have Node.js installed on your computer. If you don’t, head over to the official Node.js website and download the latest version. Once installed, you can check if it’s working by running the following command in your terminal:

node -v

This should display the version of Node.js you’ve installed.

Step 2: Create a New Next.js Project

Now that Node.js is installed, let’s create a new Next.js project. Open your terminal and run the following command:

npx create-next-app my-next-app

Here, my-next-app is the name of your project. You can replace it with whatever you’d like. This command will set up a new Next.js project with all the necessary files and dependencies.

You will be shown options to choose between Typescript or Javascript but for this tutorial we will be using Javascript

Step 3: Explore the Project Structure

Once the project is created, navigate into the project folder:

cd my-next-app

Let’s take a quick look at the folder structure:

pages/: This is where your application’s pages live. Each file in this folder corresponds to a route in your app.
public/: This folder is for static assets like images, fonts, and icons.
styles/: This folder contains your CSS files.
package.json: This file lists your project’s dependencies and scripts.

Step 4: Run the Development Server

To see your app in action, start the development server by running:

npm run dev

Once the server is running, open your browser and go to http://localhost:3000. You should see the default Next.js welcome page.

Step 5: Modify the Home Page

Let’s customize the home page. Open the pages/index.js file and replace the default code with the following:

export default function Home() {
  return (
    <div>
      <h1>Welcome to My Next.js App!</h1>
      <p>This is my first Next.js project.</p>
    </div>
  );
}

Save the file, and you’ll see the changes reflected in your browser.

Step 6: Add Styling

Next.js supports CSS modules out of the box. Let’s add some basic styling to our home page.

Go to the styles folder and open the Home.module.css file.
Add the following styles:

.container {
  text-align: center;
  margin-top: 50px;
}

.heading {
  color: #0070f3;
}

Now, import and apply the styles in pages/index.js:

import styles from "../styles/Home.module.css";

export default function Home() {
  return (
    <div className={styles.container}>
      <h1 className={styles.heading}>Welcome to My Next.js App!</h1>
      <p>This is my first Next.js project.</p>
    </div>
  );
}

Save the file, and your app should now have a centered heading with a blue color.

Step 7: Add a New Page

One of the best features of Next.js is its file-based routing. Let’s create a new page.

In the pages folder, create a new file called about.js.
Add the following code:

export default function About() {
  return (
    <div>
      <h1>About Me</h1>
      <p>This is the about page of my Next.js app.</p>
    </div>
  );
}

Save the file and navigate to http://localhost:3000/about in your browser. You should see your new page!

Conclusion

Congratulations! You’ve just set up a Next.js project from scratch, customized the home page, added styling, and created a new page. This is just the beginning— Next.js has many more features like API routes, dynamic routing, and static site generation that you can explore.

If you found this tutorial helpful, feel free to share it with others. And don’t forget to follow me on Twitter for more web development tips and tutorials.

Happy coding! 🚀

Connect with Me

Portfolio: devvick.online
GitHub: github.com/lucky-victory
Twitter: @CodewithVick

Code Repository

You can find the complete code for this project on my GitHub:

github.com/lucky-victory/nextjs-starter