Top Sites>Numbers Protocol｜Provenance infrastructure for humans and AI

No stored offer samples.

No stored action samples.

No stored product samples.

# Numbers Protocol Website - Complete Documentation for LLMs

## Project Overview

Numbers Protocol Website - A modern, responsive React application built with Vite, TypeScript, and Tailwind CSS. This is a pixel-perfect conversion of Figma designs for Numbers Protocol's provenance infrastructure platform.

**Repository**: numbersprotocol/numbers-website
**Production URL**: https://numbersprotocol.io
**Tech Stack**: React 18, TypeScript, Vite 6, Tailwind CSS, React Router DOM 6

## Key Features

- Fully responsive design (mobile, tablet, desktop)
- Static site generation for optimal performance
- MDX-based blog system with frontmatter
- Automated blog metadata generation
- SEO-optimized with sitemap.xml and robots.txt
- AI-friendly crawler permissions
- GitHub Pages deployment with SPA routing
- Dedicated ProofSnap storytelling sections for mobile and browser extension workflows

## ProofSnap Product Suite

### ProofSnap Mobile App
- Seals photos and videos with GPS, device ID, and timestamps on Numbers Mainnet the instant they are captured
- Automatically embeds C2PA manifests so editors and partners can validate provenance downstream
- Field-reporter UX with offline capture queues and one-tap sharing for rapid evidence delivery

### ProofSnap Browser Extension
- Captures full-page visuals, HTML source, and network headers in one verifiable package
- Stores assets on IPFS, timestamps them to blockchain, and injects C2PA credentials automatically
- Supports Chrome, Brave, and Edge with an "Add to Browser" CTA mirrored across hero and final CTA blocks

### Unified Evidence Workflow
- Anchored sections (`#mobile`, `#extension`) let humans and crawlers deep-link directly to each product overview
- Shared gradient CTA styling across page sections reinforces provenance-first messaging for ProofSnap queries
- Dedicated data policy at `/proofsnap/data-policy` keeps compliance guidance adjacent to product marketing

## Project Structure

```
/workspaces/numbers-website/
├── docs/                           # Main application directory
│   ├── src/
│   │   ├── App.tsx                # Main router configuration
│   │   ├── index.tsx              # Entry point
│   │   ├── components/            # Reusable React components
│   │   │   ├── BlogContent/       # Blog article display
│   │   │   ├── NavigationBar/     # Header navigation
│   │   │   ├── Footer/            # Site footer
│   │   │   ├── MDXRenderer.tsx    # MDX content renderer
│   │   │   └── PageLayout/        # Page wrapper layout
│   │   ├── screens/               # Page-level components
│   │   │   ├── Home.tsx           # Landing page
│   │   │   ├── Blog.tsx           # Blog listing page
│   │   │   ├── BlogArticle.tsx    # Individual blog post
│   │   │   ├── UseCases.tsx       # Use cases listing
│   │   │   ├── UseCaseArticle.tsx # Use case detail
│   │   │   ├── About.tsx          # About page
│   │   │   ├── Build.tsx          # Build page
│   │   │   ├── Careers.tsx        # Careers page
│   │   │   ├── Ecosystem.tsx      # Ecosystem page
│   │   │   ├── ProofSnap.tsx      # ProofSnap product page
│   │   │   └── SwapNum.tsx        # NUM token swap page
│   │   ├── data/
│   │   │   ├── blogMetadata.json  # Generated blog metadata
│   │   │   └── blogModules.ts     # Generated static imports
│   │   ├── services/              # Business logic
│   │   ├── types/                 # TypeScript type definitions
│   │   └── utils/                 # Helper functions
│   ├── blogs/                     # Blog content (MDX files)
│   │   └── YYYY-MM-DD_slug/
│   │       ├── article.mdx        # Blog content with frontmatter
│   │       └── assets/            # Blog images/media
│   ├── scripts/                   # Build scripts
│   │   ├── generateBlogMetadata.js   # Extracts blog frontmatter
│   │   ├── generateBlogModules.js    # Creates static imports
│   │   ├── generateSitemap.js        # Generates sitemap.xml
│   │   └── validateBlogs.js          # Validates blog structure
│   ├── static/                    # Static assets
│   │   ├── robots.txt             # AI-friendly crawler config
│   │   └── sitemap.xml            # Auto-generated sitemap
│   ├── plugins/                   # Vite plugins
│   │   └── blogAssets.ts          # Blog asset handling
│   ├── index.html                 # HTML entry point
│   ├── package.json               # Dependencies and scripts
│   ├── vite.config.ts             # Vite configuration
│   ├── tailwind.config.js         # Tailwind CSS config
│   └── tsconfig.json              # TypeScript config
├── .github/
│   └── workflows/                 # GitHub Actions CI/CD
└── README.md                      # Project documentation
```

## Core Technologies

### Frontend Framework
- **React 18**: Component-based UI library
- **TypeScript**: Static typing for JavaScript
- **Vite 6**: Build tool and dev server (ESM-first)
- **React Router DOM 6**: Client-side routing

### Styling
- **Tailwind CSS 3**: Utility-first CSS framework
- **tailwind-merge**: Conditional Tailwind class merging
- **tailwindcss-animate**: Animation utilities
- **clsx**: Conditional className utility

### Content Management
- **MDX (@mdx-js/react, @mdx-js/rollup)**: Markdown + JSX
- **gray-matter**: Frontmatter parsing
- **remark-frontmatter**: MDX frontmatter plugin
- **remark-mdx-frontmatter**: MDX frontmatter injection

### Utilities
- **date-fns**: Date formatting
- **lucide-react**: Icon library
- **prop-types**: Runtime prop validation

### Build Tools
- **esbuild**: Fast JavaScript bundler
- **glob**: File pattern matching
- **chokidar**: File system watcher

## Routing Configuration

Routes are defined in `docs/src/App.tsx`:

```typescript
/ (index)               → Home screen
/home                   → Home screen
/about                  → About page
/build                  → Build page  
/ecosystem              → Ecosystem page
/careers                → Careers page
/swap-num               → NUM token swap
/proofsnap              → ProofSnap product page
/proofsnap/data-policy  → Data policy page
/blog                   → Blog listing
/blog/:slug             → Individual blog article
/use-cases              → Use cases listing
/use-case-article/:slug → Use case detail page
/*                      → Fallback to Home
```

### GitHub Pages SPA Routing

The app includes a redirect handler for GitHub Pages 404-based routing:
- 404.html redirects to index.html with `?redirect=/path`
- RedirectHandler component reads the redirect parameter
- Navigates to the intended route client-side

## Blog System

### Architecture

The blog system uses **static imports** for stability and predictability:

1. **No Dynamic Imports**: Eliminates runtime import.meta.glob() issues
2. **Build-Time Generation**: Metadata and modules generated once
3. **Static Type Safety**: TypeScript knows all blog modules
4. **Predictable Bundling**: Vite can optimize better

### Blog Directory Structure

```
docs/blogs/YYYY-MM-DD_slug/
├── article.mdx          # Content with frontmatter
└── assets/              # Images and media
    └── cover.png
```

### Frontmatter Schema

```yaml
---
title: string (required)
category: TUTORIAL | GENERAL | TECH | TECHNOLOGY | ANNOUNCEMENT | GUIDE | NEWS | USE CASES
excerpt: string (required)
coverImage: ./assets/image.png (required)
author: string (optional)
date: YYYY-MM-DD (optional, defaults to folder date)
---
```

### Blog Workflow

1. **Create blog**: `docs/blogs/2025-11-17_my-article/article.mdx`
2. **Add frontmatter**: Title, category, excerpt, coverImage
3. **Run generation**: `npm run blog:build`
   - Validates all blogs
   - Generates `src/data/blogMetadata.json`
   - Generates `src/data/blogModules.ts` (static imports)
   - Generates `static/sitemap.xml`
4. **Test**: `npm run blog:preview`
5. **Commit**: Generated files + blog content

### Generated Files

**src/data/blogMetadata.json**
```json
[
  {
    "slug": "my-article",
    "title": "My Article",
    "category": "TUTORIAL",
    "excerpt": "...",
    "coverImage": "/blogs/2025-11-17_my-article/assets/cover.png",
    "date": "2025-11-17",
    "folder": "2025-11-17_my-article"
  }
]
```

**src/data/blogModules.ts**
```typescript
import article_1 from '../blogs/2025-11-17_my-article/article.mdx';
export const blogModules: Record<string, any> = {
  '2025-11-17_my-article': article_1,
};
```

## NPM Scripts

```json
{
  "dev": "vite",                                    // Start dev server
  "build": "npm run blog:build && vite build",      // Production build
  "blog:build": "npm run validate-blogs && npm run generate-blog-metadata && npm run generate-blog-modules && npm run generate-sitemap",
  "generate-blog-metadata": "node scripts/generateBlogMetadata.js",
  "generate-blog-modules": "node scripts/generateBlogModules.js",
  "generate-sitemap": "node scripts/generateSitemap.js",
  "validate-blogs": "node scripts/validateBlogs.js",
  "blog:check": "npm run validate-blogs && echo '✅ All blogs are valid!'",
  "blog:preview": "npm run blog:build && npm run dev"
}
```

## Build Scripts

### scripts/validateBlogs.js
- Scans `blogs/` directory
- Validates frontmatter presence and format
- Checks required fields (title, category, excerpt, coverImage)
- Validates category values
- Ensures blog folder naming convention (YYYY-MM-DD_slug)

### scripts/generateBlogMetadata.js
- Parses all article.mdx files
- Extracts frontmatter using gray-matter
- Generates `src/data/blogMetadata.json`
- Sorts by date (newest first)
- Computes slug from folder name

### scripts/generateBlogModules.js
- Creates `src/data/blogModules.ts`
- Generates static import statements for each blog
- Exports Record<string, any> mapping folder name to MDX component
- Enables type-safe blog loading

### scripts/generateSitemap.js
- Reads `src/data/blogMetadata.json`
- Generates `static/sitemap.xml`
- Includes static routes (/, /about, /blog, etc.)
- Includes dynamic blog routes (/blog/:slug)
- Includes use case routes (/use-case-article/:slug)
- Sets appropriate changefreq and priority values
- Uses ISO 8601 date format for lastmod

## SEO Configuration

### robots.txt (static/robots.txt)

AI-friendly configuration allowing all major crawlers:

```
User-agent: *
Allow: /

Sitemap: https://numbersprotocol.io/sitemap.xml

# AI Crawlers (explicitly allowed)
User-agent: GPTBot            # OpenAI
User-agent: OAI-SearchBot     # OpenAI Search
User-agent: ChatGPT-User      # ChatGPT
User-agent: CCBot             # Common Crawl
User-agent: Google-Extended   # Google AI
User-agent: anthropic-ai      # Anthropic
User-agent: ClaudeBot         # Claude
User-agent: Claude-Web        # Claude Web
User-agent: Claude-User       # Claude User
User-agent: cohere-ai         # Cohere
User-agent: PerplexityBot     # Perplexity
User-agent: meta-externalagent # Meta AI
User-agent: Applebot-Extended # Apple AI
User-agent: Amazonbot         # Amazon
User-agent: DuckAssistBot     # DuckDuckGo AI
User-agent: Bytespider        # ByteDance/TikTok

# Traditional Search (allowed)
User-agent: Googlebot
User-agent: Bingbot
User-agent: Slurp             # Yahoo
User-agent: DuckDuckBot
```

### sitemap.xml

Auto-generated, includes:
- Static pages with appropriate priorities (homepage: 1.0, main sections: 0.8-0.9)
- Blog articles with lastmod dates (priority: 0.6, changefreq: never)
- Use case articles (priority: 0.6, changefreq: monthly)
- All routes use https://numbersprotocol.io base URL

## Styling System

### Tailwind CSS Configuration

Custom theme extensions in `tailwind.config.js`:

**Colors:**
- Primary: Numbers Protocol brand colors
- Accent colors for CTAs and highlights
- Semantic colors (success, warning, error)

**Typography:**
- Font families: Instrument Serif, Roboto Mono, Overused Grotesk
- Custom font sizes and line heights
- Responsive typography scales

**Spacing:**
- Custom spacing scale
- Container max-widths
- Section padding utilities

**Components:**
- Custom button styles
- Card components
- Navigation styles
- Footer layouts

### CSS Architecture

- **Utility-first**: Tailwind utilities for most styling
- **Component Classes**: Extracted for repeated patterns
- **Responsive Design**: Mobile-first breakpoints (sm, md, lg, xl, 2xl)
- **Dark Mode**: Prepared for dark mode support
- **Animations**: Custom animations via tailwindcss-animate

## Component Patterns

### Page Structure

```tsx
import { PageLayout } from '../components/PageLayout';

export const MyPage = () => {
  return (
    <PageLayout
      title="Page Title"
      description="SEO description"
    >
      {/* Page content */}
    </PageLayout>
  );
};
```

### Blog Article Component

```tsx
// BlogArticle.tsx
- Reads slug from route params
- Loads blog from blogModules
- Fetches metadata from blogMetadata.json
- Renders MDX content via MDXRenderer
- Displays author, date, category
- Shows cover image
- Handles 404 for missing articles
```

### MDX Rendering

```tsx
// MDXRenderer.tsx
- Wraps MDX content with MDXProvider
- Provides custom components for MDX elements
- Handles headings, links, images, code blocks
- Applies consistent styling
- Enables component imports in MDX
```

## Deployment

### GitHub Pages

1. **Build**: `npm run build` creates `dist/` folder
2. **Deploy**: GitHub Actions pushes `dist/` to `gh-pages` branch
3. **Serve**: GitHub Pages serves from `gh-pages` branch
4. **Domain**: Custom domain configured (numbersprotocol.io)

### CI/CD Pipeline

GitHub Actions workflow (`.github/workflows/deploy.yml`):
```yaml
- Checkout code
- Setup Node.js
- Install dependencies
- Run blog:build (generates metadata, modules, sitemap)
- Build production bundle
- Deploy to gh-pages branch
```

### Environment Variables

- `SITEMAP_BASE_URL`: Override base URL for sitemap (default: https://numbersprotocol.io)

## Development Workflow

### Starting Development

```bash
cd docs
npm install
npm run blog:build  # Generate blog files
npm run dev         # Start dev server
```

### Adding a New Page

1. Create component in `src/screens/NewPage.tsx`
2. Add route in `src/App.tsx`
3. Update navigation in `src/components/NavigationBar`
4. Add to sitemap in `scripts/generateSitemap.js` (staticRoutes array)
5. Test and commit

### Adding a New Blog Post

```bash
# 1. Create blog folder
mkdir docs/blogs/2025-11-17_my-new-post

# 2. Create article.mdx
cat > docs/blogs/2025-11-17_my-new-post/article.mdx << 'EOF'
---
title: My New Post
category: TUTORIAL
excerpt: A brief description
coverImage: ./assets/cover.png
---

## Content here...
EOF

# 3. Add cover image
mkdir docs/blogs/2025-11-17_my-new-post/assets
cp ~/cover.png docs/blogs/2025-11-17_my-new-post/assets/

# 4. Generate and test
npm run blog:build
npm run dev

# 5. Commit
git add docs/blogs/2025-11-17_my-new-post
git add docs/src/data/blogMetadata.json
git add docs/src/data/blogModules.ts
git add docs/static/sitemap.xml
git commit -m "Add blog post: My New Post"
git push origin main
```

### Code Style

- **TypeScript**: Strict mode enabled
- **ESLint**: Code linting (if configured)
- **Prettier**: Code formatting (if configured)
- **Naming**: PascalCase for components, camelCase for functions/variables
- **Imports**: Absolute imports from `src/`

## Common Issues & Solutions

### Blog Not Showing

**Problem**: New blog article doesn't appear on site
**Solution**:
1. Run `npm run blog:check` to validate frontmatter
2. Ensure folder name is `YYYY-MM-DD_slug` format
3. Run `npm run blog:build` to regenerate metadata
4. Check browser console for errors
5. Verify `src/data/blogMetadata.json` includes your post

### 404 on GitHub Pages

**Problem**: Direct navigation to route shows 404
**Solution**: Already implemented - 404.html redirects to index.html with query param

### Vite Import Errors

**Problem**: Module import errors during build
**Solution**:
1. Ensure all blog MDX files have valid frontmatter
2. Run `npm run blog:build` to regenerate static imports
3. Clear Vite cache: `rm -rf node_modules/.vite`
4. Restart dev server

### Sitemap Not Updating

**Problem**: Sitemap.xml doesn't include new content
**Solution**:
1. Run `npm run generate-sitemap`
2. Or run full `npm run blog:build`
3. Commit `docs/static/sitemap.xml`

### TypeScript Errors

**Problem**: Type errors in MDX or blog modules
**Solution**:
1. Ensure `@mdx-js/react` types are installed
2. Check `tsconfig.json` includes MDX files
3. Regenerate `blogModules.ts`: `npm run generate-blog-modules`

## Key Files Reference

### App.tsx
Main application router with route definitions and redirect handler

### PageLayout.tsx
Wrapper component providing consistent page structure with navigation and footer

### BlogService.ts
Service layer for blog operations (fetching, filtering, searching)

### blogMetadata.json
Generated file with all blog metadata (DO NOT EDIT MANUALLY)

### blogModules.ts
Generated file with static MDX imports (DO NOT EDIT MANUALLY)

### vite.config.ts
Vite configuration with MDX plugin, build settings, and base path

### tailwind.config.js
Tailwind CSS theme configuration and custom utilities

### package.json
Project metadata, dependencies, and build scripts

## API Reference

### Blog Service Methods

```typescript
// Get all blogs
const blogs = blogService.getAllBlogs();

// Get blog by slug
const blog = blogService.getBlogBySlug('my-article');

// Get blogs by category
const tutorials = blogService.getBlogsByCategory('TUTORIAL');

// Search blogs
const results = blogService.searchBlogs('keyword');

// Get recent blogs
const recent = blogService.getRecentBlogs(5);
```

### MDX Components

Custom components available in MDX:

```tsx
// Headings with auto-generated IDs
<h1>, <h2>, <h3>, <h4>, <h5>, <h6>

// Enhanced links
<a href="...">

// Images with lazy loading
<img src="..." alt="..." />

// Code blocks with syntax highlighting
<pre><code className="language-js">

// Custom components (import in MDX)
import { CustomComponent } from '../components/CustomComponent';
```

## Performance Optimizations

- **Code Splitting**: Route-based code splitting via React Router
- **Lazy Loading**: Images lazy loaded by default
- **Static Generation**: Blog metadata pre-generated
- **Tree Shaking**: Vite eliminates unused code
- **Minification**: Production builds minified with esbuild
- **Asset Optimization**: Images optimized and served via CDN
- **Caching**: Proper cache headers for static assets

## Security Considerations

- **Content Security**: React automatically escapes string content, but embedded HTML in MDX is rendered without additional sanitization; only allow trusted authors or add a sanitizer if needed
- **XSS Prevention**: React's built-in escaping for props/text
- **HTTPS Only**: Enforced via GitHub Pages
- **No Sensitive Data**: No API keys or secrets in frontend code
- **Dependencies**: Regular dependency updates for security patches

## Accessibility

- **Semantic HTML**: Proper heading hierarchy, landmarks
- **ARIA Labels**: Screen reader support
- **Keyboard Navigation**: All interactive elements keyboard accessible
- **Focus States**: Visible focus indicators
- **Alt Text**: Images have descriptive alt attributes
- **Color Contrast**: WCAG AA compliant color ratios

## Browser Support

- **Modern Browsers**: Chrome, Firefox, Safari, Edge (latest 2 versions)
- **Mobile**: iOS Safari, Chrome Mobile
- **Fallbacks**: Graceful degradation for older browsers

## Testing Strategy

- **Manual Testing**: Visual regression testing
- **Browser Testing**: Cross-browser compatibility checks
- **Responsive Testing**: Mobile, tablet, desktop viewports
- **Blog Validation**: Automated via validateBlogs.js script

## Future Enhancements

Potential improvements:
- Search functionality for blogs
- Tag/category filtering
- Related articles suggestions
- Comment system integration
- Newsletter subscription
- Social media sharing
- Analytics integration
- A/B testing framework

## Contributing Guidelines

1. Fork the repository
2. Create a feature branch
3. Follow existing code style
4. Write clear commit messages
5. Test thoroughly (especially blog system)
6. Update documentation if needed
7. Submit pull request

## Contact & Support

- **Website**: https://numbersprotocol.io
- **Repository**: https://github.com/numbersprotocol/numbers-website
- **Issues**: GitHub Issues tracker

## License

Copyright © 2025 Numbers Protocol. All rights reserved.

---

**Last Updated**: November 21, 2025
**Documentation Version**: 1.0.0