Skip to content

features.md

Latest commit

 

History

History
634 lines (539 loc) · 27 KB

features.md

File metadata and controls

634 lines (539 loc) · 27 KB
Raw

BASE8 Command Center - Features & Architecture

Project Overview

BASE8 Command Center is a Next.js 16 application for a creative and marketing agency brand. It's a marketing website with mission-themed storytelling, service showcasing, project portfolio, team profiles, and lead-capture forms.

Tech Stack

  • Framework: Next.js 16 (App Router)
  • Language: TypeScript
  • UI Framework: React 19
  • Styling: Tailwind CSS 3
  • Form Handling: React Hook Form + Zod validation
  • Animations: Framer Motion
  • Form Backend: Formspree (external service)
  • Analytics: Vercel Analytics & Speed Insights
  • Component Library: Radix UI (headless) + shadcn/ui patterns

Architecture: Next.js App Router

This is a server-first Next.js application:

src/
├── app/                    # Next.js App Router (server components by default)
│   ├── layout.tsx          # Root layout with metadata, fonts, providers
│   ├── page.tsx            # Home page
│   ├── globals.css         # Global styles
│   ├── robots.ts           # SEO - robots.txt generation
│   ├── sitemap.ts          # SEO - XML sitemap
│   ├── not-found.tsx       # 404 fallback page
│   ├── providers.tsx       # Client-side providers (Context, React Query)
│   └── [route]/            # Route segments
│       ├── layout.tsx      # Page-specific layout
│       ├── page.tsx        # Page component
│       └── ...
├── components/             # Reusable React components
│   ├── ui/                 # Headless UI components (Radix UI + shadcn/ui)
│   │   ├── button.tsx
│   │   ├── form.tsx
│   │   ├── input.tsx
│   │   ├── select.tsx
│   │   ├── slider.tsx
│   │   ├── sonner.tsx
│   │   ├── textarea.tsx
│   │   ├── tooltip.tsx
│   │   └── label.tsx
│   ├── Navbar.tsx          # Top navigation (client component)
│   ├── Footer.tsx          # Footer (server component)
│   ├── PageWrapper.tsx     # Page animation wrapper (client)
│   ├── CTASection.tsx      # Call-to-action section (client)
│   ├── ServiceCard.tsx     # Service display card (client)
│   ├── ProjectCard.tsx     # Project portfolio card (client)
│   ├── TeamCard.tsx        # Team member card (client)
│   └── SectionHeader.tsx   # Section title component (client)
├── lib/                    # Utilities and helpers
│   ├── seo.ts             # Schema.org JSON-LD utilities
│   ├── utils.ts           # Tailwind cn() utility
│   └── data.ts            # Centralized data (future)
└── public/                # Static assets
    ├── assets/            # Images
    └── LOGO BASE 8 HQ.png

Route Structure

Route Component Purpose
/ page.tsx Home page with hero, services, projects, team
/operational-units operational-units/page.tsx Service offerings breakdown
/mission-archive mission-archive/page.tsx Portfolio with filtering
/headquarters headquarters/page.tsx About page
/strike-team strike-team/page.tsx Team profiles
/deploy-mission deploy-mission/page.tsx Lead capture form (projects)
/contact contact/page.tsx Lead capture form (inquiry)
* not-found.tsx 404 fallback

Features Implemented

Core Functionality

  • ✅ Multi-page Next.js app with App Router
  • ✅ Responsive navigation (desktop + mobile)
  • ✅ SEO optimized (metadata, robots.txt, sitemap)
  • ✅ Structured data (Schema.org JSON-LD)
  • ✅ TypeScript strict mode
  • ✅ ESLint configured

Forms & Validation

  • ✅ Contact form (React Hook Form + Zod)
  • ✅ Deploy Mission form (React Hook Form + Zod + dynamic fields)
  • ✅ Client-side validation
  • ✅ Async submission to Formspree
  • ✅ Error handling and feedback

UI & Design

  • ✅ Tailwind CSS with custom design system
  • ✅ Glassmorphism effects
  • ✅ Glow animations
  • ✅ Responsive grid layouts
  • ✅ Framer Motion page transitions
  • ✅ Dark theme default with CSS variables
  • ✅ Custom Orbitron + Inter fonts

Analytics & Performance

  • ✅ Vercel Analytics integration
  • ✅ Vercel Speed Insights (Core Web Vitals)
  • ✅ Next.js Image optimization
  • ✅ Next.js Font optimization
  • ✅ Automatic code splitting

Developer Experience

  • ✅ TypeScript strict mode
  • ✅ ESLint + Prettier
  • ✅ Path aliases (@/*) for clean imports
  • ✅ Component composition
  • ✅ Zod for runtime validation

Features Not Yet Implemented

  • ❌ Backend API routes
  • ❌ Database/persistence
  • ❌ Error boundaries (error.tsx)
  • ❌ Loading states (loading.tsx)
  • ❌ Authentication/authorization
  • ❌ Automated tests
  • ❌ Server actions (form submission via Server Actions)

Key Patterns

Server vs Client Components

// ✅ Server Component (default)
// src/app/layout.tsx
export const metadata: Metadata = { /* ... */ };
export default function RootLayout({ children }) {
  // Can access databases, APIs, secrets
  // No useState, useEffect, etc.
}

// ✅ Client Component (interactive)
// src/components/Navbar.tsx
"use client";
import { useState, useEffect } from "react";
export default function Navbar() {
  const [mobileOpen, setMobileOpen] = useState(false);
  // Can use hooks, browser APIs
}

Form Validation Pattern

// Define schema with Zod
const schema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

// Use with React Hook Form
const form = useForm({
  resolver: zodResolver(schema),
});

// Submit to external API
const onSubmit = async (data) => {
  await fetch(process.env.NEXT_PUBLIC_FORM_URL, {
    method: "POST",
    body: JSON.stringify(data),
  });
};

Component Composition

// Reusable card components
<ServiceCard icon={Shield} title="..." description="..." />
<ProjectCard name="..." category="..." image="..." />
<TeamCard name="..." role="..." image="..." />

Environment Variables

Required for production:

# .env.local (in project root)
NEXT_PUBLIC_CONTACT_FORM_URL=https://formspree.io/f/YOUR_ID
NEXT_PUBLIC_DEPLOY_FORM_URL=https://formspree.io/f/YOUR_ID

Deployment

Vercel (Recommended)

  1. Connect repository to Vercel
  2. Set environment variables in Vercel dashboard
  3. Deploy: vercel --prod

Local Development

npm install
npm run dev          # Start dev server on http://localhost:3000
npm run build        # Build for production
npm start            # Start production server
npm run lint         # Run ESLint

Performance Targets

  • ✅ Lighthouse: 90+
  • ✅ Core Web Vitals: All green
  • ✅ Build time: <30s
  • ✅ Page load: <2s (3G)

Future Roadmap

  1. Phase 1: Server Actions for form submission (remove client fetches)

  2. Phase 2: Add error boundaries and loading states

  3. Phase 3: Automated E2E tests with Playwright

  4. Phase 4: Backend API + Database (if needed)

  5. Phase 5: Email notifications via Resend/SendGrid Files: src/pages/Index.tsx, src/components/ServiceCard.tsx, src/components/ProjectCard.tsx, src/components/TeamCard.tsx, src/components/CTASection.tsx Status: Implemented

  6. Operational Units listing What: Displays eight operational divisions with explicit sub-category capability lists. How: A typed units array (title, icon, services[]) renders animated command-board cards with unit index labels and capability-count badges (OPS). Files: src/pages/OperationalUnits.tsx Status: Implemented

  7. Mission Archive filtering What: Allows category-based filtering of project cards. How: Local filter state and derived filtered list with conditional array filter operation. Files: src/pages/MissionArchive.tsx, src/components/ProjectCard.tsx Status: Implemented

  8. Headquarters positioning content What: Communicates BASE8HQ foundation statement, mission, vision, and operational philosophy with animated cards. How: Structured two-paragraph About copy plus a values grid rendered with framer-motion fade-in patterns. Files: src/pages/Headquarters.tsx Status: Implemented

  9. Strike Team interactive profiles What: Team cards flip on hover from profile front to dossier back, then reset when the cursor leaves. How: Local flipped state per card driven by onMouseEnter/onMouseLeave, 3D transform classes, hidden backfaces, smooth rotateY transition easing, and stat bars. Files: src/components/TeamCard.tsx, src/pages/StrikeTeam.tsx, src/pages/Index.tsx Status: Implemented

  10. Shadow Operatives roster What: Displays secondary classified role cards. How: Static role array mapped into card-glass placeholders. Files: src/pages/StrikeTeam.tsx Status: Implemented

  11. Contact intelligence panel What: Contact page presents fixed communication channels and social placeholders. How: Icon + label/value mapping rendered in card blocks and icon links. Files: src/pages/Contact.tsx Status: Implemented

  12. Global CTA conversion surfaces What: Calls-to-action route users toward project intake and contact. How: Reusable CTASection plus navbar/home/footer CTA links. Files: src/components/CTASection.tsx, src/components/Navbar.tsx, src/pages/Index.tsx Status: Implemented

Backend Features

  1. Backend architecture status What: No backend service exists in this repository. How: No server runtime, no API route directory, no database adapter, no ORM, no migration files. Files: package.json, README.md Status: Not implemented (intentional current architecture)

  2. External submission pipeline (Contact) What: Submits validated contact payload to an external endpoint. How: fetch(import.meta.env.VITE_CONTACT_FORM_URL) with POST, JSON body, and response status check. Files: src/pages/Contact.tsx, src/vite-env.d.ts Status: Implemented

  3. External submission pipeline (Deploy Mission) What: Submits validated mission payload to an external endpoint. How: fetch(import.meta.env.VITE_DEPLOY_FORM_URL) with POST, JSON body, and response status check. Files: src/pages/DeployMission.tsx, src/vite-env.d.ts Status: Implemented

  4. Client-side validation gate before submit (Contact) What: Enforces payload quality before network submission. How: Zod schema + react-hook-form resolver. Validation details:

  • name: minimum 2 characters
  • email: valid email format
  • message: minimum 10 characters Files: src/pages/Contact.tsx Status: Implemented
  1. Client-side validation gate before submit (Deploy Mission) What: Enforces mission-brief requirements before network submission. How: Zod schema + react-hook-form resolver. Validation details:
  • name: minimum 2 characters
  • company: minimum 2 characters
  • email: valid email format
  • project_type: required (non-empty)
  • budget: optional
  • timeline: optional
  • description: minimum 20 characters Files: src/pages/DeployMission.tsx Status: Implemented

  1. Submission lifecycle handling What: Handles async states around submission request lifecycle. How: Local state flags isSubmitting, submitted, submitError; disables submit buttons while pending. Files: src/pages/Contact.tsx, src/pages/DeployMission.tsx Status: Implemented

  2. Error signaling and fallback behavior What: Detects non-2xx responses and keeps user on form. How: Throws on !response.ok, catches and logs error, does not set success state. Files: src/pages/Contact.tsx, src/pages/DeployMission.tsx Status: Implemented

  3. Type-safe environment contract for endpoints What: Prevents untyped environment access. How: Extends ImportMetaEnv with required VITE_CONTACT_FORM_URL and VITE_DEPLOY_FORM_URL. Files: src/vite-env.d.ts Status: Implemented

  4. Security posture currently present What: Keeps secrets/config local and avoids hardcoded endpoint values in source. How: .env and .env.* gitignored, env variable indirection used at runtime. Files: .gitignore, README.md Status: Implemented

  5. Security and backend controls currently absent What: No in-repo rate limiting, auth, anti-bot verification logic, or server-side data validation layer. How: Architecture delegates submission to Formspree; no custom backend middleware exists in code. Files: package.json, src/pages/Contact.tsx, src/pages/DeployMission.tsx Status: Not implemented (externalized)

Frontend Features

  1. Design system and theme tokens What: Centralized visual language with dark theme defaults and golden primary accent (#F5A623). How: CSS custom properties and Tailwind theme extension. Files: src/index.css, tailwind.config.ts Status: Implemented

  2. Glassmorphism + glow visual style What: Reusable card and button aesthetics that define brand look. How: .card-glass, .btn-glow, .btn-glow-filled, glow separator, scan line, noise overlay, and glow color values tuned to #F5A623-based rgba/HSL tokens. Files: src/index.css Status: Implemented

  3. Responsive navigation system What: Sticky navbar with desktop links and animated mobile menu. How: Breakpoint-conditioned layouts (lg), mobileOpen state toggle, AnimatePresence transitions, route-aware active style. Files: src/components/Navbar.tsx Status: Implemented

  4. Route-change scroll reset What: Eliminates stale scroll position when navigating between pages. How: Watches pathname and calls window.scrollTo(0, 0). Files: src/components/ScrollToTop.tsx Status: Implemented

  5. Page transition animation wrapper What: Gives consistent fade transitions for page sections. How: Framer motion wrapper with initial/animate/exit opacity states. Files: src/components/PageWrapper.tsx Status: Implemented

  6. Section header abstraction What: Consistent heading structure for page sections. How: Reusable component with tag, title, and subtitle props. Files: src/components/SectionHeader.tsx Status: Implemented

  7. Service card module What: Reusable unit card with icon, title, description, and staggered entrance. How: Motion card component receiving icon and content props; currently used for homepage unit summaries. Files: src/components/ServiceCard.tsx Status: Implemented

  8. Operational capability command-board cards What: Unit-specific cards on the Operational Units page expose exact sub-category service lists. How: motion.article cards render icon, unit label (UNIT XX), OPS count badge, and row-level capability items from each unit's services[] array. Files: src/pages/OperationalUnits.tsx Status: Implemented

  9. Project card module What: Reusable project card with gradient overlay and hover zoom. How: Motion wrapper and group-hover image scaling. Files: src/components/ProjectCard.tsx Status: Implemented

  10. Team card 3D dossier module What: Hover-triggered card flipping between profile and intel stats. How: useState hover state, onMouseEnter/onMouseLeave triggers, 3D perspective, rotateY transforms, smooth easing/duration tuning, hidden backfaces, and stat-width class mapping. Files: src/components/TeamCard.tsx Status: Implemented

  11. Form component abstraction What: Consistent form controls and accessible error messaging. How: shadcn form wrappers around react-hook-form context (FormField, FormItem, FormMessage, FormControl). Files: src/components/ui/form.tsx Status: Implemented

  12. Form controls used in lead flows What: Inputs, textarea, select dropdowns, and button variants used in both lead forms. How: Reusable UI components from shadcn stack with Tailwind class overrides. Files: src/components/ui/input.tsx, src/components/ui/textarea.tsx, src/components/ui/select.tsx, src/components/ui/button.tsx Status: Implemented

  13. Mission Archive client filtering UX What: User toggles category tabs to narrow visible project cards. How: filter state + inline button controls + conditional style by active category. Files: src/pages/MissionArchive.tsx Status: Implemented

  14. Success confirmation states for forms What: Replaces form UI with confirmation card after successful submission. How: Conditional rendering based on submitted boolean. Files: src/pages/Contact.tsx, src/pages/DeployMission.tsx Status: Implemented

  15. Loading-state submit labels What: Provides immediate action feedback while request is in flight. How: Conditional button text (Sending..., Deploying...) plus disabled state. Files: src/pages/Contact.tsx, src/pages/DeployMission.tsx Status: Implemented

  16. Social icon link placeholders What: Visual social channels exist but destination URLs are placeholders. How: Static href="#" links in contact/footer sections. Files: src/pages/Contact.tsx, src/components/Footer.tsx Status: Implemented (placeholder destinations)

  17. Global click sound feature What: Plays click SFX on interactive targets. How: Global capture-phase document listener, target selector matching, disabled target skipping, reusable audio instance. Files: src/lib/clickSound.ts, src/main.tsx, src/assets/sound effects/click sound 1.wav Status: Implemented

  18. Mobile breakpoint utility hook What: Exposes isMobile boolean tied to width threshold. How: matchMedia listener around 768px breakpoint. Files: src/hooks/use-mobile.tsx Status: Implemented

  19. Toast state engine What: Reducer-driven toast queue with update/dismiss/remove actions. How: In-memory state + listener fan-out + delayed removal queue. Files: src/hooks/use-toast.ts, src/components/ui/use-toast.ts Status: Implemented (infrastructure; low active usage in pages)

  20. NotFound fallback and route debugging What: Handles unknown routes with user-facing 404 and developer console output. How: Catch-all route in app + path-specific error log in component effect. Files: src/App.tsx, src/pages/NotFound.tsx Status: Implemented

  21. UI primitive inventory (shadcn + Radix) What: Large reusable primitive set available for future expansion. How: Component files under ui folder. Files: src/components/ui Available primitives:

  • accordion
  • alert-dialog
  • alert
  • aspect-ratio
  • avatar
  • badge
  • breadcrumb
  • button
  • calendar
  • card
  • carousel
  • chart
  • checkbox
  • collapsible
  • command
  • context-menu
  • dialog
  • drawer
  • dropdown-menu
  • form
  • hover-card
  • input-otp
  • input
  • label
  • menubar
  • navigation-menu
  • pagination
  • popover
  • progress
  • radio-group
  • resizable
  • scroll-area
  • select
  • separator
  • sheet
  • sidebar
  • skeleton
  • slider
  • sonner
  • switch
  • table
  • tabs
  • textarea
  • toast
  • toaster
  • toggle-group
  • toggle
  • tooltip
  • use-toast Status: Implemented as component inventory

Integrations

  1. Formspree What: Third-party form backend used for both lead flows. How: Direct browser POST to environment-configured endpoints. Files: src/pages/Contact.tsx, src/pages/DeployMission.tsx, src/vite-env.d.ts Status: Implemented

  2. Framer Motion What: Animation engine for entrance, transitions, and motion interactions. How: motion.* elements and AnimatePresence patterns. Files: src/pages/Index.tsx, src/components/Navbar.tsx, src/components/PageWrapper.tsx, src/components/TeamCard.tsx Status: Implemented

  3. React Hook Form + Zod What: Typed form handling and schema validation. How: useForm, zodResolver, schemas, and shadcn form wrappers. Files: src/pages/Contact.tsx, src/pages/DeployMission.tsx, src/components/ui/form.tsx Status: Implemented

  4. shadcn + Radix UI What: Accessible primitives and composable UI building blocks. How: Local component wrappers and utility classes. Files: components.json, src/components/ui Status: Implemented

  5. React Query What: Query caching and async-state foundation. How: Global QueryClient initialized and provided at app root. Files: src/App.tsx Status: Implemented as infrastructure (not heavily consumed by page logic)

  6. Playwright fixture integration What: E2E test harness integration point. How: Standard Playwright configuration and fixture re-export from @playwright/test. Files: playwright.config.ts, playwright-fixture.ts Status: Implemented as infrastructure

Non-Functional Features

  1. Build performance and dev velocity What: Fast local dev and modern build output. How: Vite + SWC plugin, HMR, optimized static bundle output. Files: vite.config.ts, package.json Status: Implemented

  2. Type safety and compile-time checks What: TypeScript strict mode with path aliasing and project references. How: tsconfig hierarchy with strict flags and noEmit compilation. Files: tsconfig.json, tsconfig.app.json, tsconfig.node.json Status: Implemented

  3. Linting and code consistency What: Enforces React hooks and general TypeScript lint quality. How: ESLint flat config with scoped rule customization for UI primitives. Files: eslint.config.js Status: Implemented

  4. Browser compatibility support What: CSS processing supports vendor prefixing and Tailwind transforms. How: PostCSS pipeline with autoprefixer. Files: postcss.config.js Status: Implemented

  5. Responsive layout strategy What: Mobile-first page composition with breakpoint-specific grids and nav behavior. How: Tailwind responsive utilities and custom mobile hook. Files: src/index.css, src/hooks/use-mobile.tsx, src/components/Navbar.tsx Status: Implemented

  6. Accessibility support in forms What: Inputs expose aria-invalid and descriptive error IDs for assistive tech. How: shadcn form control wiring through FormControl, FormMessage, and generated ids. Files: src/components/ui/form.tsx Status: Implemented

  7. Deployment readiness for static host What: Build output and env conventions align with Vercel deployment flow. How: Production build to dist, env vars documented, no server runtime dependency. Files: README.md, package.json Status: Implemented

  8. Testing maturity snapshot What: Test toolchain exists but feature-level coverage is minimal. How: Vitest config and setup present with placeholder example test; Playwright config present without substantial suites. Files: vitest.config.ts, src/test/setup.ts, src/test/example.test.ts, playwright.config.ts Status: Partially implemented

  9. Vendor-neutral toolchain baseline What: Build/test/runtime config no longer relies on Lovable-specific plugins or wrappers. How: Vite uses standard React SWC plugin only, Playwright uses standard @playwright/test config + fixture, and Lovable metadata references have been removed from HTML/config docs. Files: vite.config.ts, playwright.config.ts, playwright-fixture.ts, index.html, package.json Status: Implemented

Architecture Snapshot

  • Frontend runtime: React SPA with route-driven page composition and reusable animated components.
  • Backend/API: None in repository.
  • Data source: Static in-code arrays and external Formspree endpoints for form submission.
  • Persistence: Externalized through integration provider; no in-repo database schema.
  • State management: Local component state + react-hook-form state + prepared React Query provider.
  • Error model: Local try/catch around fetch requests, inline message rendering, console logging.

Maintenance Log

Update Protocol

When this file is updated in future prompts, append a new entry with:

  • Date (YYYY-MM-DD)
  • Author/Agent
  • Change Type (Added, Updated, Deprecated, Removed)
  • Feature IDs or section names touched
  • Files impacted
  • Rationale
  • Verification performed (lint/build/tests/manual)

Log Entries

  • 2026-04-04 | GitHub Copilot (GPT-5.3-Codex) | Added | Initial comprehensive feature baseline | features.md | Generated from full codebase audit across pages, components, config, and tests | Verification: File created and content aligned to current source
  • 2026-04-04 | GitHub Copilot (GPT-5.3-Codex) | Updated | Operational Units redesign, homepage unit-summary narrative refresh, HQ About copy refresh, #F5A623 palette adoption, and vendor-neutral Lovable cleanup | features.md, src/pages/OperationalUnits.tsx, src/pages/Index.tsx, src/pages/Headquarters.tsx, src/index.css, vite.config.ts, playwright.config.ts, playwright-fixture.ts, index.html, package.json | Keep documentation synchronized with current implementation and branding/tooling decisions | Verification: npm run lint, npm run build
  • 2026-04-04 | GitHub Copilot (GPT-5.3-Codex) | Updated | Strike Team card interaction model changed from click-toggle to hover-in/hover-out flip with smoother slower transition tuning | features.md, src/components/TeamCard.tsx | Keep feature documentation aligned with current UX interaction behavior | Verification: Manual source verification against TeamCard implementation