project-structure

# Project Structure ## Source Layout `src/` is the application root. - `src/components/`: reusable UI components. PascalCase filenames matching the component name (e.g. `VideoCard.tsx`). - `src/pages/`: route-level page components. `*Page.tsx` naming (e.g. `HomePage.tsx`, `ProfilePage.tsx`). - `src/hooks/`: custom React hooks. `useX` naming in `.ts` files (e.g. `useNostr.ts`). - `src/lib/`: utilities, helpers, non-React logic. - `src/contexts/`: React context providers and their associated hooks. - `src/types/`: shared TypeScript type definitions and interfaces. - `src/test/`: test setup (`setup.ts`) and shared test utilities. - `src/config/`: runtime configuration and constants. - `src/data/`: static data files and fixtures. - `src/styles/`: global CSS and style definitions beyond Tailwind utilities. ## Entry Point Flow ``` index.html → src/main.tsx → src/App.tsx → src/AppRouter.tsx ``` ## Import Alias `@/` maps to `src/`. Configured in `tsconfig.json` paths and `vite.config.ts` resolve.alias. Use `@/` for all app imports. ## Public Assets `public/` holds static assets served as-is: `manifest.webmanifest`, `_redirects`, and other files that don't need processing. ## Build Output `dist/` receives the production build. During build, `index.html` is copied to `404.html` to support SPA routing on static hosts. ## Configuration Files | File | Purpose | |------|---------| | `vite.config.ts` | Vite build configuration | | `tailwind.config.ts` | TailwindCSS configuration | | `eslint.config.js` | ESLint configuration | | `tsconfig.json` | Root TypeScript config | | `tsconfig.app.json` | App source TypeScript config | | `tsconfig.node.json` | Node/tooling TypeScript config | ## Custom ESLint Rules `eslint-rules/` contains project-specific rules: `no-inline-script`, `no-placeholder-comments`, `require-webmanifest`. No inline `eslint-disable` comments. ## Build Scripts `scripts/` holds build and utility scripts: - `copy-well-known.mjs` / `verify-well-known.mjs`: handle `.well-known` files - `prerender-legal.mjs`: prerender legal pages - `generate-icons.js`: generate app icons - `precalculate-hashtag-thumbnails.ts`: precompute thumbnail data - `verify-relay-config.ts`: validate relay configuration - `audit-microcopy.mjs` / `a11y-audit.mjs`: content and accessibility audits ## Documentation `docs/` contains project documentation: - `docs/brand/`: brand guidelines and assets - `docs/superpowers/plans/`: implementation plans - `docs/superpowers/specs/`: feature specifications - `docs/` root: architecture docs, relay docs, migration guides ## File Placement Quick Reference | Adding a... | Put it in... | Named... | |------------|-------------|----------| | New page | `src/pages/` | `FooPage.tsx` | | New component | `src/components/` | `Foo.tsx` | | New hook | `src/hooks/` | `useFoo.ts` | | New utility | `src/lib/` | `foo.ts` | | New context | `src/contexts/` | `FooContext.tsx` | | New type | `src/types/` | `foo.ts` | | New test | Next to source | `foo.test.ts` or `foo.test.tsx` |