Project Structure

A guide to Miko402's codebase organization to help you navigate, modify, and extend the project.

Directory Overview

miko402/
├── app/                          # Next.js App Router directory
│   ├── api/                      # API routes
│   │   └── chat/
│   │       └── route.js          # Chat API endpoint
│   ├── app/                      # Chat application page
│   │   └── page.js               # Chat interface
│   ├── components/               # Shared React components
│   │   └── MatrixRain.js         # Background animation
│   ├── globals.css               # Global styles & Tailwind
│   ├── layout.js                 # Root layout component
│   └── page.js                   # Landing page
├── docs/                         # Documentation (GitBook)
│   ├── getting-started/
│   ├── features/
│   ├── architecture/
│   └── ...
├── public/                       # Static assets
├── .env.local                    # Environment variables (gitignored)
├── .env.example                  # Environment template
├── .gitignore                    # Git ignore rules
├── next.config.js                # Next.js configuration
├── package.json                  # Dependencies & scripts
├── postcss.config.js             # PostCSS configuration
├── tailwind.config.js            # Tailwind CSS configuration
└── README.md                     # Project README

Core Files

`/app/layout.js` — Root Layout

Wraps all pages with shared structure:

import { JetBrains_Mono } from 'next/font/google';
import './globals.css';

export const metadata = {
  title: 'Miko402 - Autonomous AI Payment Agent',
  description: 'Autonomous payments powered by x402...',
};

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={jetbrainsMono.variable}>{children}</body>
    </html>
  );
}

Defines app-wide metadata, loads fonts, imports global styles, and provides consistent page structure.

`/app/page.js` — Landing Page

The marketing and onboarding page featuring:

Hero section with animated text and CTAs
Feature grid highlighting core capabilities
"How It Works" section (x402 payment flow)
Use cases for developers, API providers, and $MIKO holders
FAQ and footer

Technologies: Framer Motion for animations, Lucide React for icons.

`/app/app/page.js` — Chat Interface

The primary interaction surface where users communicate with Miko:

Real-time streaming chat with the AI
Wallet connection and status display
Rate limiting with 50-second cooldown
localStorage persistence for cooldown state
Markdown rendering for AI responses

State management:

const [input, setInput] = useState('');
const [cooldownRemaining, setCooldownRemaining] = useState(0);
const [lastSubmitTime, setLastSubmitTime] = useState(0);

`/app/api/chat/route.js` — Chat API

Backend endpoint that powers all conversations:

Receives user messages
Configures the AI model (Gemini 2.0 Flash via OpenRouter)
Applies the system prompt with security layers
Enables web search tools
Streams responses back to the client

export const maxDuration = 50;

const result = streamText({
  model: google('gemini-2.0-flash-exp'),
  tools: {
    google_search: google.tools.googleSearch({}),
    url_context: google.tools.urlContext({}),
  },
  system: systemPrompt,
  messages: convertToModelMessages(messages),
  temperature: 0.7,
  maxTokens: 4000,
});

`/app/globals.css` — Global Styles

Tailwind CSS imports and custom styles:

@import "tailwindcss";

/* Custom markdown styles */
.markdown-content { ... }

/* Custom animations */
@keyframes pulse { ... }

Next.js App Router

Miko402 uses Next.js 16's App Router architecture.

File-Based Routing

/app/page.js → http://localhost:3000/
/app/app/page.js → http://localhost:3000/app
/app/api/chat/route.js → http://localhost:3000/api/chat

Server vs Client Components

Server Components (default):

/app/layout.js — Better performance, smaller bundle

Client Components ('use client'):

/app/page.js — Uses Framer Motion
/app/app/page.js — Interactive chat
/app/components/MatrixRain.js — Canvas animation

Data Flow

User Message Flow

User Input
    ↓
Submit Handler (app/app/page.js)
    ↓
Rate Limit Check
    ↓
sendMessage() via useChat hook
    ↓
POST /api/chat
    ↓
System Prompt + User Message
    ↓
Gemini AI Model
    ↓
Stream Response
    ↓
Display in Chat UI

Rate Limiting Flow

Submit Attempt
    ↓
Check lastSubmitTime in state
    ↓
Check localStorage
    ↓
If < 50 seconds → Block + Show Countdown
If >= 50 seconds → Allow + Set New Timestamp
    ↓
Store timestamp in localStorage
    ↓
Start countdown timer

State Management

Miko402 uses React hooks exclusively:

useState — Local component state
useEffect — Side effects (timers, localStorage)
useRef — DOM references (scroll position)
useChat — Vercel AI SDK hook for chat functionality

Persistent State

localStorage — Rate limit timestamps only
Session — None (stateless by design)
Database — None (privacy-first)

Styling Architecture

Tailwind CSS 4

Utility-first CSS with the Miko402 crimson theme:

<div className="px-6 py-4 bg-[#E84A5F]/5 border border-[#E84A5F]/20">

Color Palette

#E84A5F — Crimson (primary brand color)
Opacity modifiers: /5, /10, /20 for subtle backgrounds and borders

Responsive Design

Mobile-first approach:

<div className="text-xl md:text-3xl lg:text-5xl">

Build Process

Development

npm run dev

Hot module replacement, Tailwind CSS processing, port 3000 by default.

Production

npm run build
npm start

Enables minification, tree-shaking, CSS purging, code splitting, and static generation where possible.

Dependencies

Core

Package

Purpose

Version

next

React framework

16.0.0

react

UI library

19.2.0

ai

Vercel AI SDK

5.0.76

@ai-sdk/google

Google AI integration

2.0.23

@ai-sdk/react

React hooks for AI

2.0.76

UI

Package

Purpose

tailwindcss

Utility CSS framework

framer-motion

Animation library

lucide-react

Icon library

react-markdown

Markdown rendering

remark-gfm

GitHub Flavored Markdown

Performance

Code Splitting

Next.js automatically splits code by route—separate bundles for the landing page, chat page, and shared components.

Streaming Responses

AI responses stream token-by-token for faster perceived performance and progressive rendering.

Image Optimization

Next.js Image component provides automatic WebP conversion, lazy loading, and responsive sizing.

Extension Points

Where to add new features:

New pages: /app/your-page/page.js
New API routes: /app/api/your-route/route.js
New components: /app/components/YourComponent.js
Shared utilities: /lib/utils.js (create if needed)

Smart Contracts — On-chain infrastructure
Chat API — API endpoint details
Configuration — Environment setup

PreviousBest Practices NextSmart Contracts

Last updated 13 hours ago

Good night

hashtagDirectory Overview

hashtagCore Files

hashtag/app/layout.js — Root Layout

hashtag/app/page.js — Landing Page

hashtag/app/app/page.js — Chat Interface

hashtag/app/api/chat/route.js — Chat API

hashtag/app/globals.css — Global Styles

hashtagNext.js App Router

hashtagFile-Based Routing

hashtagServer vs Client Components

hashtagData Flow

hashtagUser Message Flow

hashtagRate Limiting Flow

hashtagState Management

hashtagPersistent State

hashtagStyling Architecture

hashtagTailwind CSS 4

hashtagColor Palette

hashtagResponsive Design

hashtagBuild Process

hashtagDevelopment

hashtagProduction

hashtagDependencies

hashtagCore

hashtagUI

hashtagPerformance

hashtagCode Splitting

hashtagStreaming Responses

hashtagImage Optimization

hashtagExtension Points

hashtagRelated Documentation