Codebase Map

Map of the FluxKit codebase.

Top-level ownership

• src/: Next.js App Router UI/runtime.
• convex/: Convex data model, queries, mutations, actions, HTTP router.
• docs/: planning docs used by the application team.

Path: package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "typecheck": "bunx convex codegen && tsc --noEmit",
    "test": "TZ=UTC bun test"
  }
}

Frontend runtime map (src/)

• src/app/layout.tsx: root providers, auth token handoff, global error boundary/toaster.
• src/app/(landing)/*: public marketing pages and content sections.
• src/app/(dashboard)/*: authenticated workspace shell and feature pages.
• src/app/api/auth/[...all]/route.ts: Better Auth route handler export.
• src/proxy.ts: redirect/auth-cookie/rate-limit gate before route handling.

Path: src/app/api/auth/[...all]/route.ts

import { handler } from "@/lib/auth/server";
 
export const { GET, POST } = handler;

Path: src/app/(dashboard)/layout.tsx

import { useQuery, Authenticated, Unauthenticated, AuthLoading } from "convex/react";
import { api } from "@/convex/_generated/api";
 
const user = useQuery(api.user.getCurrentProfile);
 
<Unauthenticated>
  <RedirectToSignIn />
</Unauthenticated>
<Authenticated>{/* dashboard shell */}</Authenticated>

Backend map (convex/)

• convex/schema.ts: tables + indexes.
• convex/http.ts: HTTP route registration + auth endpoint rate-limiting wrapper.
• convex/auth.ts: base current-user identity query.
• convex/user.ts: profile and onboarding mutations.
• convex/tasks.ts: CRUD + task stats + completion-triggered notifications.
• convex/notifications.ts: pagination/read-state APIs and internal notification insert.
• convex/features/auth/*: Better Auth setup and plugin wiring.
• convex/features/organization/*: org and invitation operations via Better Auth APIs.
• convex/polar.ts: billing product/subscription adapter registration.

Path: convex/features/auth/auth.ts

export const authComponent = createClient<DataModel, typeof schema>(
  components.betterAuth,
  {
    local: { schema },
    verbose: false,
  },
);
 
export const createAuth = (ctx: GenericCtx<DataModel>) => {
  return betterAuth(createAuthOptions(ctx));
};

Path: convex/polar.ts

export const polar: Polar<DataModel> = new Polar<DataModel>(components.polar, {
  getUserInfo: async (ctx) => {
    const user = await ctx.runQuery(api.auth.getCurrentUser);
    if (!user?.subject || !user?.email)
      throw new Error("Invalid user data: missing id or email");
    return { userId: user.subject, email: user.email };
  },
  products: { pro: POLAR_PRO_PRODUCT_ID, teams: POLAR_TEAMS_PRODUCT_ID },
  server: POLAR_SERVER_MODE,
});

Request/data boundaries

• Browser to Next.js: route grouping, server/client component split, cookie-based pre-checks.
• Next.js to Convex: ConvexReactClient transport plus generated API bindings.
• Convex to Better Auth/Polar: component adapter calls inside handlers and registered HTTP routes.
• Convex to DB: typed defineTable schema and per-query index usage.