Frontend Architecture

apps/web/src/
├── router.tsx              # Router config
├── routeTree.gen.ts        # Auto-generated routes
├── routes/                 # File-based routes
│   ├── __root.tsx          # Root layout
│   ├── index.tsx           # Home page
│   └── _github/            # GitHub routes
├── components/             # React components
│   ├── layout/             # Header, footer
│   ├── repo/               # Repo-specific
│   ├── chat/               # Chat UI
│   └── ui/                 # shadcn components
├── lib/                    # Utilities
└── styles/                 # Global styles

import { createRouter } from '@tanstack/react-router';
import { ConvexQueryClient } from '@convex-dev/react-query';

const convex = new ConvexClient(import.meta.env.VITE_CONVEX_URL);
const convexQueryClient = new ConvexQueryClient(convex);

export const router = createRouter({
  routeTree,
  context: {
    queryClient: new QueryClient(),
    convexReactClient: convex,
    convexQueryClient
  }
});

/ (root)
├── /                                  # Home
├── /explore                           # Explore repos
├── /sign-in                           # Sign in
├── /about                             # About page
├── /api/auth/$                        # Better Auth API
│
└── /_github/                          # GitHub layout
    ├── /$owner                        # Owner profile
    │
    └── /$owner/$repo/                 # Repo layout
        ├── /                          # Summary
        ├── /refresh                   # Re-index
        │
        ├── /arch/                     # Architecture
        │   ├── /                      # Entity list
        │   └── /$slug                 # Entity detail
        │
        ├── /issues/                   # Issues
        │   ├── /                      # Issue list
        │   └── /$number               # Issue detail
        │
        ├── /pr/                       # Pull requests
        │   ├── /                      # PR list
        │   └── /$number               # PR detail
        │
        └── /chat/                     # Chat
            ├── /                      # New chat
            └── /$chatId               # Chat thread

// routes/_github/$owner_.$repo/route.tsx
export const Route = createFileRoute('/_github/$owner_/$repo')({
  component: RepoLayout
});

function RepoLayout() {
  return (
    <div className="grid grid-cols-[250px,1fr]">
      <Sidebar />
      <Outlet /> {/* Child routes render here */}
    </div>
  );
}

// routes/_github/$owner_.$repo/index.tsx
export const Route = createFileRoute('/_github/$owner_/$repo/')({
  component: RepoSummary
});

function RepoSummary() {
  const { owner, repo } = Route.useParams();
  const fullName = `${owner}/${repo}`;
  const repoData = useQuery(api.repos.getByFullName, { fullName });

  if (!repoData) return <Skeleton />;
  return <SummaryView repo={repoData} />;
}

import { ConvexBetterAuthProvider } from '@convex-dev/better-auth/react';

export const Route = createRootRoute({
  component: RootLayout
});

function RootLayout() {
  const { convexReactClient, convexQueryClient } = useRouterContext();

  return (
    <ConvexBetterAuthProvider client={convexReactClient}>
      <Outlet />
    </ConvexBetterAuthProvider>
  );
}

import { useQuery } from '@convex-dev/react-query';
import { api } from '@offworld/backend';

const repo = useQuery(api.repos.getByFullName, {
  fullName: "facebook/react"
});
// Auto-subscribes, updates on DB changes

import { useMutation } from '@convex-dev/react-query';

const startAnalysis = useMutation(api.repos.startAnalysis);

// Trigger mutation
await startAnalysis.mutateAsync({ fullName: "facebook/react" });

import { useAction } from '@convex-dev/react-query';

const getOwnerInfo = useAction(api.github.getOwnerInfo);

// Trigger action
const ownerData = await getOwnerInfo({ owner: "facebook" });

function RepoPage() {
  const repo = useQuery(api.repos.getByFullName, { fullName });

  if (!repo) return <Skeleton />;
  if (repo.status === "queued") return <QueuedState />;
  if (repo.status === "processing") return <ProgressIndicator />;
  if (repo.status === "failed") return <ErrorState />;

  return <RepoContent repo={repo} />;
}

function ArchitectureTab() {
  const entities = useQuery(api.architectureEntities.getByRepo, { repoId });

  return (
    <div>
      {entities?.map(entity => (
        <EntityCard key={entity._id} entity={entity} />
      ))}
      {!entities && <EmptyState />}
    </div>
  );
}

// TypeScript knows owner and repo are strings
const { owner, repo } = Route.useParams();

// packages/backend/convex/_generated/api.d.ts
import { api } from '@offworld/backend';

// TypeScript knows this function expects { fullName: string }
useQuery(api.repos.getByFullName, { fullName });

import { useNavigate } from '@tanstack/react-router';

const navigate = useNavigate();

// Navigate to route
navigate({
  to: '/_github/$owner/$repo',
  params: { owner: 'facebook', repo: 'react' }
});

import { Link } from '@tanstack/react-router';

<Link
  to="/_github/$owner/$repo/issues/$number"
  params={{ owner, repo, number: 123 }}
>
  Issue #123
</Link>

<div className="flex items-center gap-4 p-6 bg-card rounded-lg">
  <Button variant="outline" size="sm">Click</Button>
</div>

export default {
  darkMode: ['class'],
  // dark: prefix automatically applied
}

<div className="bg-white dark:bg-gray-900">
  Content
</div>