Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
194 lines (168 loc) · 5.68 KB

ARCHITECTURE.md

File metadata and controls

194 lines (168 loc) · 5.68 KB

Project Architecture and .gitignore

This repository is initialized for a Next.js app using the app/ directory, with a clean, scalable structure designed for VS Code + Copilot. It contains only code structure and ignores — no workflow or PR rules.

📁 Project Architecture

.
├─ app/
│  ├─ (marketing)/                 # Public site group
│  │  ├─ layout.tsx                # Global layout (Header / Footer / SEO)
│  │  ├─ page.tsx                  # Home
│  │  ├─ team/
│  │  │  ├─ page.tsx
│  │  │  └─ components/            # Team-page local components
│  │  ├─ associates/
│  │  │  ├─ page.tsx
│  │  │  └─ components/            # Associates-page local components
│  │  └─ companies/
│  │     ├─ page.tsx
│  │     └─ components/            # Companies-page local components
│  ├─ api/
│  │  ├─ apply/route.ts            # Application form endpoint
│  │  └─ contact/route.ts          # Contact form endpoint
│  ├─ sitemap.ts
│  └─ robots.ts
│
├─ components/                     # Reusable design-system components
│  ├─ ui/                          # Atomic elements (Button/Card/Accordion/...)
│  ├─ layout/                      # Container / Section / Header / Footer
│  ├─ sections/                    # Page-level sections (Hero/FeatureList/FAQ/ProcessSteps/Stats)
│  └─ shared/                      # Small shared pieces (AvatarGroup/Badge/IconLabel)
│
├─ features/                       # Composite client features with logic
│  ├─ application-form/
│  │  ├─ schema.ts
│  │  ├─ components/
│  │  └─ index.tsx
│  └─ contact-form/
│     └─ index.tsx
│
├─ content/                        # Static data or CMS-ready configs
│  ├─ team.json
│  ├─ associates.ts
│  └─ companies.ts
│
├─ lib/
│  ├─ types.ts                     # Global TypeScript types
│  ├─ utils.ts                     # Utility helpers (cn, formatters)
│  └─ seo.ts                       # Metadata / SEO helpers
│
├─ styles/
│  ├─ globals.css
│  └─ tailwind.css
│
├─ public/
│  └─ images/
│
└─ tests/
   ├─ unit/
   └─ e2e/

Layer Summary

  • app/ – Page entries (mostly Server Components). Each page imports content and assembles UI/section/feature components.
  • components/ui – Atomic, stateless UI primitives (from shadcn/ui).
  • components/layout – Global wrappers and site-wide structure.
  • components/sections – Visual, data-driven page sections (no internal text).
  • components/shared – Tiny reusable fragments (badges, avatars, icons).
  • features/ – Interactive or stateful client modules such as forms.
  • content/ – Structured data feeding pages; easily replaceable with a CMS later.
  • lib/ – Types, helpers, and SEO utilities.
  • styles/ – Global Tailwind setup and tokens.
  • tests/ – Unit + E2E structure placeholders.

Type Contracts (lib/types.ts)

export type FeatureItem = { title: string; desc: string; icon?: string };
export type StepItem    = { title: string; desc: string };
export type FAQItem     = { q: string; a: string };
export type StatItem    = { label: string; value: string | number };

export type TeamMember = {
  name: string;
  role: string;
  avatarUrl?: string;
  group?: "board" | "member" | "advisor";
};

Section Component Props

Component Props
Hero { title: string; subtitle?: string; cta?: { label: string; href: string } }
FeatureList { items: FeatureItem[] }
ProcessSteps { steps: StepItem[] }
FAQ { items: FAQItem[] }
Stats { items: StatItem[] }

All section components are purely presentational — no business logic or hard-coded copy.

🧱 .gitignore

# --- Node / Next.js build artifacts ---
node_modules/
.next/
out/
dist/
build/
.cache/
coverage/
*.log
npm-debug.log*
pnpm-debug.log*
yarn-debug.log*
yarn-error.log*

# --- Environment / secrets ---
.env
.env.*
!.env.example

# --- TypeScript ---
*.tsbuildinfo

# --- Editor & OS junk ---
.vscode/*
!.vscode/extensions.json
!.vscode/settings.json
.idea/
*.swp
*.swo
.DS_Store
Thumbs.db

# --- Tests / Playwright / Jest ---
playwright-report/
test-results/
coverage/
jest-stare/
*.snap

# --- Storybook / shadcn (optional) ---
.storybook/
stories-static/
*.stories.*
storybook-static/

# --- Lint / formatting caches ---
.eslintcache
.prettiercache

# --- Local temp data ---
tmp/
temp/
*.tmp
*.local
*.bak
*.orig

# --- Vercel / build outputs ---
.vercel/
vercel_build_output/

# --- Logs / misc ---
*.pid
*.seed
*.pid.lock
npm-error.log
*.log.*

# --- Optional artifacts ---
*.tgz
*.tar.gz
*.zip
*.pem
*.crt
*.key

Key points:

  • Keeps only unified VS Code settings files (extensions.json, settings.json).
  • Excludes environment secrets but retains .env.example.
  • Ignores TypeScript build info and all temporary caches.
  • Covers Playwright/Jest outputs, Storybook artifacts, and Vercel previews.
  • Safe for cross-platform dev on macOS, Windows, or Linux.

This file and structure give a clean, reproducible foundation. Developers can branch independently on app/(marketing)/…, components/, or features/ without merge noise, while the repo stays lightweight.