Repository Architecture

This document describes the structural conventions used across the Polar Edge monorepo. Follow these patterns when adding features, refactoring, or creating new apps. 
 
 Monorepo Layout 
 The repository is a Turborepo monorepo managed with pnpm workspaces . 
 polar-edge/
├── apps/
│ ├── scouting/ # Main scouting app (Next.js 16 + Turbopack)
│ ├── basecamp/ # Backend service (NestJS, Discord bot, Sheets)
│ └── basecamp-fe/ # Frontend for Basecamp features (Next.js)
├── packages/
│ ├── ui/ # Shared Radix UI component library
│ ├── tba-sdk/ # The Blue Alliance API TypeScript client
│ ├── ai/ # Shared AI/LLM utilities
│ ├── twofa/ # Two-factor authentication utilities
│ ├── typescript-config/
│ └── vitest-config/
└── turbo.json
 
 Key rules: 
 
 Business logic lives in apps/ — packages are pure utilities with no app-specific logic. 
 Shared packages are consumed as workspace dependencies ( @repo/ui , @repo/tba-sdk , etc.). 
 Run tasks through Turbo: turbo build , turbo dev --filter=scouting , etc. Don't run app scripts directly unless you have a reason. 
 
 
 Feature-First Architecture 
 Both Next.js apps ( scouting and basecamp-fe ) use a feature-first layout. The src/app/ directory is intentionally thin — it contains only Next.js routing files. All business logic, data access, and feature-specific components live in src/features/ . 
 src/
├── app/ ← Routing only. Pages delegate to features.
├── features/ ← Primary home for all business logic.
│ └── <feature>/
│ ├── actions.ts # Server actions
│ ├── queries.ts # Database reads
│ ├── types.ts # Feature-specific types
│ ├── components/ # Feature-specific React components
│ ├── hooks/ # Feature-specific client hooks
│ └── contexts/ # Feature-specific React contexts
├── components/ ← Shared UI used across multiple features (nav, layout, etc.)
└── lib/ ← Pure utilities and library config. No feature logic.
 
 The benefit: when you need to find or change anything about the "picklist" feature, you go to src/features/picklist/ . You don't have to hunt across src/app/ , src/utils/ , src/api/ , etc. 
 
 App Router Conventions 
 Pages are thin 
 Pages ( page.tsx ) should authenticate, load data, and compose feature components. They should not contain business logic themselves. 
 // ✅ Good — app/admin/members/page.tsx
export default function MembersPage() {
 return (
 <main className="container mx-auto max-w-5xl px-4 py-8">
 <TypographyH1>Team Members</TypographyH1>
 <Suspense fallback={<LoadingTable />}>
 <MembersContent /> {/* async RSC from features/ */}
 </Suspense>
 </main>
 );
}
 
 The data-fetching and rendering logic lives in MembersContent , which is an async RSC imported from src/features/org/members/ . 
 Async Server Components for data 
 Prefer async RSCs for data fetching. Place the async component in features/ and import it into the page: 
 // features/org/members/components/MembersContent.tsx
async function MembersContent() {
 const activeMember = await requireAdminMember();
 const members = await fetchMembers(activeMember.organizationId);
 return <MembersTable members={members} />;
}
 
 Suspense boundaries 
 Wrap async data-fetching components in <Suspense> in the page. Provide a meaningful skeleton as the fallback — not just a spinner. This enables streaming and prevents the whole page from blocking. 
 <Suspense fallback={<LoadingTable />}>
 <MembersContent />
</Suspense>
 
 
 Feature Module Anatomy 
 Each feature in src/features/<feature>/ follows this file structure. Not every file is required — only create what the feature needs: 
 
 
 
 File / Directory 
 Purpose 
 
 
 
 
 actions.ts 
 Next.js Server Actions ( "use server" ). Mutations only — auth, validate, write DB. 
 
 
 queries.ts 
 Database reads. Always import "server-only" . Use "use cache" for expensive reads. 
 
 
 types.ts 
 TypeScript types and interfaces specific to this feature. 
 
 
 components/ 
 React components used only by this feature. 
 
 
 hooks/ 
 Client-side React hooks used only by this feature. 
 
 
 contexts/ 
 React context providers used only by this feature. 
 
 
 *.test.ts 
 Tests co-located with the code they test. 
 
 
 
 Example — picklist feature: 
 src/features/picklist/
├── actions.ts # createPicklist, deletePicklist, reorderTeams, etc.
├── queries.ts # getPicklistsForOrganization, etc.
├── types.ts # PicklistTeam, PicklistWithTeams, etc.
└── components/
 ├── CreatePicklistDialog.tsx
 ├── PicklistTeamsTable.tsx
 ├── DeletePicklistButton.tsx
 └── ...
 
 Example — nested features ( org ): 
 When a domain has sub-features with distinct concerns, nest them: 
 src/features/org/
├── settings/
│ ├── actions.ts
│ └── components/OrganizationSettingsForm.tsx
├── members/
│ ├── actions.ts
│ └── components/
│ ├── RemoveMemberButton.tsx
│ └── RoleSelect.tsx
└── invites/
 ├── actions.ts
 └── components/InviteLinkManager.tsx
 
 
 Server Actions Pattern 
 Server actions live in features/<feature>/actions.ts and always follow this order: 
 "use server";

export async function exampleAction(input: unknown) {
 // 1. Authenticate — get session
 const session = await auth.api.getSession({ headers: await headers() });
 if (!session) return { error: "Unauthorized" };

 // 2. Authorize — get active org member (role check if needed)
 const member = await auth.api.getActiveMember({ headers: await headers() });
 if (!member) return { error: "No active organization" };

 // 3. Context — get active event if relevant
 const event = await getActiveEventForOrganization(member.organizationId);
 if (!event) return { error: "No active event" };

 // 4. Validate input
 const validated = schema.safeParse(input);
 if (!validated.success) return { error: "Invalid input" };

 // 5. Write — use a transaction for multi-table operations
 const result = await db.transaction(async (tx) => {
 // ... perform operations
 return data;
 });

 // 6. Return success or error (never throw to the client)
 return { success: true, data: result };
}
 
 Rules: 
 
 Always return { error: string } or { success: true, ... } — never throw. 
 Use db.transaction() when writing to multiple tables atomically. 
 Validate every external input with Zod before touching the database. 
 Do not perform mutations from queries.ts — keep reads and writes separate. 
 
 
 Data Queries & Caching 
 Database reads live in features/<feature>/queries.ts . Always mark this file as server-only: 
 import "server-only";
 
 This prevents accidental import in client components and gives a clear build-time error if it happens. 
 Use "use cache" for expensive reads 
 For reads that are called frequently or are expensive, use Next.js's "use cache" directive with cacheLife and cacheTag : 
 import "server-only";
import { cacheLife, cacheTag } from "next/cache";
import { cacheTags } from "@/lib/cache";

export async function getStandFormCounts(
 organizationId: string,
 eventId: string | null
) {
 "use cache";
 cacheLife("hours");
 cacheTag(cacheTags.leaderboardStand(organizationId));

 return db
 .select({ ... })
 .from(standForm)
 .where(...);
}
 
 Cache tag centralization 
 All cache tag strings are defined in src/lib/cache.ts . Never hardcode tag strings at the call site — always use the cacheTags object: 
 // src/lib/cache.ts
export const cacheTags = {
 leaderboardStand: (organizationId: string) => `leaderboard-stand-${organizationId}`,
 teamMetrics: (eventId: string) => `team-metrics-${eventId}`,
 // ...
};
 
 When a mutation invalidates cached data, call revalidateTag(cacheTags.leaderboardStand(orgId)) in the relevant server action. 
 Parallel data fetching 
 When a page or component needs multiple independent pieces of data, fetch them in parallel with Promise.all : 
 const [organization, members] = await Promise.all([
 auth.api.getFullOrganization({ ... }),
 auth.api.listMembers({ ... }),
]);
 
 
 RSC Boundaries — Server vs Client 
 Next.js components are Server Components by default . Only add "use client" when a component needs browser APIs, state, or event handlers. 
 Server Components (default) 
 
 Fetch data directly (async/await) 
 Access cookies, headers, environment variables 
 Import server-only code (DB, auth, etc.) 
 Cannot use useState , useEffect , or browser APIs 
 
 Client Components ( "use client" ) 
 
 Interactive UI — event handlers, state, effects 
 Browser APIs ( window , localStorage , timers) 
 Third-party client libraries 
 React context providers that hold state 
 
 Minimize the client boundary 
 Push "use client" as deep into the component tree as possible. A good pattern: keep the page and data-fetching wrapper as RSCs, and only mark leaf components (buttons, forms, interactive widgets) as client: 
 // ✅ Good — page stays server, only the interactive button is client
// app/picklist/[id]/page.tsx (RSC)
export default async function PicklistPage({ params }) {
 const picklist = await getPicklist(params.id); // server query
 return <PicklistView picklist={picklist} />;
}

// features/picklist/components/DeletePicklistButton.tsx
"use client";
export function DeletePicklistButton({ id }) { ... }
 
 Context providers 
 Context providers must be client components (they use React state internally). The pattern: create a <FeatureProvider> client component that wraps its children, and mount it as high as needed in the tree without making parent RSCs into client components. 
 // features/totp/contexts/TOTPContext.tsx
"use client";
export function TOTPProvider({ secret, children }) { ... }

// app/@auth/page.tsx (RSC — just renders the provider)
export default async function AuthPage() {
 const secret = (await cookies()).get("toofaSecret")?.value;
 return (
 <TOTPProvider secret={secret}>
 <FlipperWrapper />
 </TOTPProvider>
 );
}
 
 
 Centralized Routes 
 All route paths are defined in src/lib/routes.ts . Never hardcode route strings in components or actions — always import from routes . 
 // src/lib/routes.ts
export const routes = {
 home: "/",
 admin: {
 root: "/admin",
 members: "/admin/members",
 invites: "/admin/invites",
 event: "/admin/event",
 settings: "/admin/settings",
 },
 analysis: {
 team: (teamNumber: number | string) => `/analysis/teams/${teamNumber}` as const,
 },
 // ...
} as const;
 
 Usage: 
 import { routes } from "@/lib/routes";

<Link href={routes.admin.members}>Members</Link>
<Link href={routes.analysis.team(1234)}>Team 1234</Link>
 
 Why: Refactoring a URL means changing one place. TypeScript catches broken references at build time. 
 
 Parallel Routes (Conditional UI) 
 When a page needs to show fundamentally different UI based on auth state (or another condition), use Next.js parallel routes rather than conditional rendering in a single component. 
 The basecamp-fe app uses this for its auth gate: 
 app/
├── layout.tsx # Renders both slots: {props.auth} and {props.unauth}
├── @auth/
│ └── page.tsx # Shown when authenticated
└── @unauth/
 └── page.tsx # Shown when unauthenticated
 
 // app/layout.tsx
export default function RootLayout(props: LayoutProps<"/">) {
 return (
 <html>
 <body>
 {props.unauth} {/* renders @unauth/page.tsx */}
 {props.auth} {/* renders @auth/page.tsx */}
 </body>
 </html>
 );
}
 
 Each slot independently validates auth state and returns null if not applicable: 
 // app/@auth/page.tsx
export default async function AuthPage() {
 const token = (await cookies()).get("toofaToken")?.value;
 if (!token || !(await validateToken(token))) return null;
 // render authenticated UI
}

// app/@unauth/page.tsx
export default async function UnauthorizedPage() {
 const token = (await cookies()).get("toofaToken")?.value;
 if (token && (await validateToken(token))) return null;
 return <SignInForm />;
}
 
 When to use parallel routes: 
 
 Auth gates where the two states are visually distinct pages (not just a hidden button) 
 Dashboard layouts with independently loading panels 
 Modal overlays with intercepting routes 
 
 When NOT to use them: Simple show/hide toggles — use conditional rendering in a single component. 
 
 Shared UI Components 
 @repo/ui — cross-app design system 
 Radix UI primitives with Tailwind v4 styling. Import from the package path: 
 import { Button } from "@repo/ui/components/button";
import { Dialog, DialogContent, DialogTrigger } from "@repo/ui/components/dialog";
import { Table, TableBody, TableCell, TableHead } from "@repo/ui/components/table";
 
 Use @repo/ui components as building blocks. Don't recreate primitives (buttons, inputs, dialogs) from scratch. 
 src/components/ — cross-feature app components 
 Components that are used by multiple features within the same app but aren't generic enough for @repo/ui : 
 
 Navigation ( Navbar , Sidebar ) 
 Layout wrappers 
 App-wide indicators (offline status, toasts) 
 
 Rule: If a component is only used by one feature, it belongs in src/features/<feature>/components/ , not src/components/ . 
 
 Lib Directory Rules 
 src/lib/ is for pure utilities and library configuration. It has no feature logic. 
 
 
 
 Path 
 Contents 
 
 
 
 
 lib/auth.ts 
 Better Auth configuration 
 
 
 lib/auth-client.ts 
 Client-side auth helpers 
 
 
 lib/permissions.ts 
 Super admin checks 
 
 
 lib/routes.ts 
 Centralized route definitions 
 
 
 lib/cache.ts 
 Cache tag constants 
 
 
 lib/utils.ts 
 Generic utility functions ( cn , etc.) 
 
 
 lib/compress-image.ts 
 Image compression utility 
 
 
 lib/database/ 
 Drizzle client, schema tables, relations, views, types 
 
 
 lib/server/ 
 Server-side helpers: auth guards, org helpers, storage, TBA, tokens 
 
 
 lib/offline/ 
 Network status, offline queue context, toasts 
 
 
 
 What does NOT go in lib/ : 
 
 Feature-specific actions, queries, or components 
 Anything that imports from features/ 
 
 
 Where Does My Code Go? 
 Use this decision tree when adding new code: 
 Is it a Next.js routing file (page, layout, loading, error)?
 └─ Yes → src/app/<route>/

Is it a database read?
 └─ Yes → src/features/<feature>/queries.ts (with "server-only" import)

Is it a mutation / form submission handler?
 └─ Yes → src/features/<feature>/actions.ts (with "use server")

Is it a React component used only by one feature?
 └─ Yes → src/features/<feature>/components/

Is it a React component used by multiple features?
 └─ Yes → src/components/ (if app-specific) or packages/ui (if cross-app)

Is it a React hook used only by one feature?
 └─ Yes → src/features/<feature>/hooks/

Is it a React context / provider for one feature?
 └─ Yes → src/features/<feature>/contexts/

Is it a route path string?
 └─ Yes → src/lib/routes.ts

Is it a cache tag string?
 └─ Yes → src/lib/cache.ts

Is it a shared type for one feature?
 └─ Yes → src/features/<feature>/types.ts

Is it a generic utility with no feature dependency?
 └─ Yes → src/lib/utils.ts (or a new focused file in src/lib/)
 
 
 Quick Reference 
 
 
 
 Convention 
 Rule 
 
 
 
 
 Default RSC 
 All components are server by default; "use client" only when needed 
 
 
 Data fetching 
 Async RSC + queries.ts with "use cache" for expensive reads 
 
 
 Mutations 
 Server Actions in actions.ts ; always auth → validate → transact → return 
 
 
 Routes 
 All paths in src/lib/routes.ts ; never hardcode strings 
 
 
 Cache tags 
 All tags in src/lib/cache.ts via cacheTags object 
 
 
 Feature isolation 
 Each feature is self-contained; no cross-feature imports 
 
 
 Client boundary 
 Push "use client" as deep as possible 
 
 
 server-only 
 All queries.ts files start with import "server-only" 
 
 
 UI primitives 
 Use @repo/ui — don't reinvent buttons, dialogs, tables 
 
 
 Suspense 
 Wrap async RSCs in <Suspense> with skeleton fallbacks