Project structure

Ludicord uses file conventions: location and filename determine what a module becomes. The generator starts small, while the framework supplies built-in fallbacks for optional convention files.

#Generated application tree

1app/
2├── pages.tsx
3├── globals.css
4├── minimize.tsx
5├── auth/
6│   ├── loading.tsx
7│   ├── error.tsx
8│   └── denied.tsx
9├── embeds/
10│   ├── home/embed.tsx
11│   └── me/embed.tsx
12├── api/
13│   └── hello/route.ts
14└── ws/
15    └── audience/route.ts

The starter also includes components/, lib/, public/, ludicord.config.mjs, environment templates, generated route declarations, and TypeScript configuration.

#What each location owns

Do not import a server route into a client component. Communicate across the boundary with fetch() or useWS().

#How paths become routes

The folders under embeds, api, and ws become URL segments. Route groups in parentheses organize code without changing the public path.

1app/embeds/home/embed.tsx              → home
2app/embeds/profile/[id]/embed.tsx      → profile/:id
3app/embeds/(games)/chess/embed.tsx     → chess
4app/api/player/[id]/route.ts           → /api/player/:id
5app/ws/room/[roomId]/route.ts          → /ws/room/:roomId

Starting development or a build updates ludicord.generated.d.ts. This makes route strings and dynamic params available to TypeScript without a manual route registry.

#The fixed filenames

An embed component is always embed.tsx and should default-export a React component named embed. An HTTP or WebSocket module is always route.ts. The stable names let the compiler distinguish framework boundaries from ordinary colocated modules.

1export default function embed() {
2  return <main>Game screen</main>;
3}

Components, helpers, schemas, tests, and assets may live beside a route. Only recognized convention filenames become public routes.

#Root and nested boundaries

pages.tsx owns providers that should survive screen navigation. Embed folders can add nested layout.tsx files and nearest loading or error boundaries when advanced sections need them. Keep ordinary screen-specific UI beside the embed that uses it.

#Files outside app

#Next step

Configure Discord setup before depending on real user, guild, channel, or Activity-instance data.