The Interop

Content for Builders, Founders, and Funders

A minimal, neumorphic personal site for The Interop newsletter — weekly insights at the intersection of AI, business transformation, and emerging technology.

🌐 Live Sites

Primary: jessealton.com
Redirect: theinterop.com → jessealton.com

✨ Features

Neumorphic Design — Soft, modern UI with tasteful shadows and depth
Three.js Hero — Interactive constellation visualization (progressive enhancement)
Dark/Light Mode — System-aware with manual toggle
MDX Blog — Rich content with code highlighting and embeds
SEO Optimized — Sitemap, RSS, OpenGraph, structured data
Reduced Motion Support — Respects user preferences
Git-First Authoring — Write in Cursor/IDE, push to publish
Content Validation — CI fails on broken frontmatter or missing assets

🚀 Quick Start

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production (includes content validation)
npm run build

# Start production server
npm start

📝 Authoring Workflow

Creating a New Post

# Interactive mode
npm run new:post

# With arguments
npm run new:post "Your Post Title" --category=ai-strategy --tags=agents,interop

This creates:

content/posts/YYYY/YYYY-MM-DD-your-post-title.mdx
public/images/blog/YYYY/your-post-title/ (asset folder)

Post File Structure

Posts use the canonical format:

content/posts/
├── 2025/
│   ├── 2025-12-29-call-tracking-is-dead.mdx
│   └── 2025-10-01-on-ai-modernization.mdx
└── 2024/
    └── 2024-04-03-we-ask-ai-to-do-things.mdx

Frontmatter Schema

---
title: "Your Post Title"                    # Required
date: "2025-12-29"                          # Required, ISO format
slug: "your-post-title"                     # Required, kebab-case, unique
excerpt: "One to three sentence summary."   # Required
category: "ai-strategy"                     # Required, from controlled list
tags: ["agents", "interop"]                 # Optional but recommended
coverImage: "/images/blog/2025/slug/cover.png"  # Optional
featured: false                             # Optional
draft: true                                 # Optional, excludes from production
canonicalUrl: ""                            # Optional, for Substack legacy URLs
updatedDate: "2025-12-30"                   # Optional
series: "Interop Notes"                     # Optional, for grouped navigation
---

Valid Categories

Slug	Label
`ai-strategy`	AI Strategy
`business-transformation`	Business Transformation
`agent-development`	Agent Development
`future-tech`	Future Tech
`case-studies`	Case Studies

Draft Posts

Set draft: true in frontmatter to exclude a post from production builds. Draft posts still appear in development mode.

Publishing Workflow

Create post: npm run new:post "Title"
Edit in Cursor/IDE
Preview: npm run dev
Set draft: false when ready
Commit and push to GitHub
Vercel deploys automatically

✅ Content Validation

The build validates all posts for:

Required frontmatter fields
Valid ISO date format (YYYY-MM-DD)
Unique slugs (no duplicates)
Valid category (from controlled list)
Existing cover image files (if specified)

Manual Validation

# Run content validation only
npm run lint:content

CI Integration

The npm run build command runs content validation first. CI will fail if:

Required fields are missing or empty
Date format is invalid
Slug is duplicated
Category is not in the controlled list

🧩 MDX Components

Posts support standard Markdown plus these MDX components:

Callout

<Callout type="info" title="Note">
  Important information here.
</Callout>

Types: note, info, warn, success, tip

Figure

<Figure 
  src="/images/blog/2025/slug/diagram.png" 
  alt="Architecture diagram"
  caption="System architecture overview"
/>

PullQuote

<PullQuote author="Jesse Alton" source="The Interop">
  The future belongs to those who can make different systems work together.
</PullQuote>

Embed

<Embed type="youtube" id="dQw4w9WgXcQ" title="Video title" />
<Embed type="twitter" id="1234567890" />
<Embed type="loom" id="abc123" />

🔄 Migrating from Substack

Export your Substack data:
- Go to Settings → Exports → Export posts
- Download and unzip the export

Run the migration script:

npm run migrate ./path/to/substack-export

Review and validate:
```
npm run lint:content
```
Preview the site:
```
npm run dev
```

📁 Project Structure

theinterop/
├── content/
│   └── posts/              # MDX blog posts (by year)
│       ├── 2025/
│       └── 2024/
├── public/
│   └── images/
│       └── blog/           # Post assets (by year/slug)
├── scripts/
│   ├── new-post.ts         # Post scaffolding CLI
│   ├── validate-content.ts # Content validation
│   └── migrate-substack.ts # Migration tool
├── src/
│   ├── app/                # Next.js App Router pages
│   ├── components/
│   │   ├── layout/         # Header, Footer
│   │   ├── mdx/            # Callout, Figure, PullQuote, Embed
│   │   ├── three/          # Three.js scenes
│   │   └── ui/             # Reusable UI components
│   └── lib/                # Utilities and types
└── ...config files

🎨 Design System

The site uses a neumorphic design system with CSS custom properties:

Colors

Variable	Light	Dark
`--color-background`	`hsl(240 10% 96%)`	`hsl(240 15% 8%)`
`--color-foreground`	`hsl(240 10% 10%)`	`hsl(240 10% 95%)`
`--color-accent-primary`	`hsl(220 90% 56%)`	Same

Typography

Display: Sora
Body: Inter
Mono: JetBrains Mono

Key Components

.neu-card — Neumorphic card with hover elevation
.neu-button — Neumorphic button with press effect
.neu-input — Inset input fields
.text-gradient — Accent gradient text

🔧 Configuration

Site Config (`src/lib/types.ts`)

export const siteConfig: SiteConfig = {
  name: 'The Interop',
  description: 'Content for Builders, Founders, and Funders...',
  url: 'https://jessealton.com',
  // ... more config
};

Environment Variables

# Optional: Analytics
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

🌐 Deployment

Vercel (Recommended)

Push to GitHub
Import project to Vercel
Add domains:
- jessealton.com (primary)
- theinterop.com (redirect to primary)

Domain Redirects

vercel.json configures 301 redirects from theinterop.com → jessealton.com.

📊 Performance Targets

Metric	Target
Performance	≥ 90
Accessibility	≥ 90
Best Practices	≥ 90
SEO	≥ 90

🛠 Tech Stack

Framework: Next.js 16 (App Router)
Language: TypeScript
Styling: Tailwind CSS v4
3D Graphics: Three.js + React Three Fiber
Content: MDX with gray-matter
Icons: Lucide React
Deployment: Vercel

📄 Scripts Reference

Command	Description
`npm run dev`	Start development server
`npm run build`	Build for production (validates content first)
`npm run start`	Start production server
`npm run lint`	Run ESLint
`npm run lint:content`	Validate all posts
`npm run new:post`	Scaffold a new post
`npm run migrate`	Migrate Substack export
`npm run type-check`	TypeScript type check

🔒 Security

This repository implements several security measures:

Rate Limiting: Admin login limited to 5 attempts per 15 minutes per IP
HTTP-Only Cookies: Session tokens protected from XSS
Environment Variables: All secrets stored as env vars, never in code
Session Expiry: Admin sessions expire after 7 days
Bearer Token Auth: Newsletter API protected with API key
No Sensitive Data: Database credentials only in Vercel environment

Environment Variables Required

# Database (Vercel Postgres)
POSTGRES_URL=
POSTGRES_PRISMA_URL=
POSTGRES_URL_NON_POOLING=

# Email (Resend)
RESEND_API_KEY=

# Admin System
ADMIN_PASSWORD=              # Generate with: npm run admin:password
NEWSLETTER_API_KEY=          # For newsletter automation

Admin Dashboard

Access at /admin with credentials:

Email: [email protected]
Password: Set via ADMIN_PASSWORD environment variable

Generate secure password: npm run admin:password

📄 License

AltonTech Proprietary License — This code is available for viewing and reference purposes ONLY. No use, copying, or modification permitted without explicit written permission. See LICENSE.md for full terms.

Violations result in automatic assignment of all derivative works to AltonTech, Inc.

For licensing inquiries: [email protected]

Built with ☕ by Jesse Alton

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.github/workflows		.github/workflows
content		content
public		public
scripts		scripts
src		src
.gitignore		.gitignore
ADMIN_SETUP.md		ADMIN_SETUP.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
SOCIAL_SHARING.md		SOCIAL_SHARING.md
drizzle.config.ts		drizzle.config.ts
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vercel.json		vercel.json

License

mrmetaverse/theinterop

Folders and files

Latest commit

History

Repository files navigation