Skip to content

ARCANEA_SIMPLE_ARCHITECTURE.md

Latest commit

 

History

History
502 lines (399 loc) · 13.1 KB

ARCANEA_SIMPLE_ARCHITECTURE.md

File metadata and controls

502 lines (399 loc) · 13.1 KB
Raw

Arcanea: The Simple Architecture (Pragmatic Choice)

Reality Check: Start simple. Optimize later.

🎯 The Truth About Architecture

The Hybrid System (Previous Recommendation)

Pros:

  • ✅ Optimal performance (Astro static pages)
  • ✅ Lowest cost at scale ($80/mo vs $170/mo)
  • ✅ Specialized tools for specialized jobs

Cons:

  • ❌ TWO systems to maintain
  • ❌ TWO deployment pipelines
  • ❌ TWO domains to manage
  • ❌ More complexity (shared packages, versioning)
  • ❌ Cognitive overhead (where does this feature go?)
  • ❌ Slower iteration (context switching)

The Simple System (THIS IS BETTER FOR NOW)

One Next.js app. Everything in Vercel. Done.

Pros:

  • ✅ ONE system to build and maintain
  • ✅ ONE deployment (Vercel handles everything)
  • ✅ ONE domain (arcanea.ai + app.arcanea.ai)
  • ✅ Faster shipping (no context switching)
  • ✅ Can STILL use Obsidian (MDX files in repo)
  • ✅ Can STILL optimize later (migrate to hybrid when needed)

Cons:

  • ⚠️ Slightly higher costs at scale (but manageable)
  • ⚠️ Slightly larger bundles (but App Router mitigates this)

🏗️ The Simple Architecture

arcanea/                          # Single monorepo
├── apps/
│   └── web/                      # Next.js 16 app (EVERYTHING)
│       ├── app/
│       │   ├── (marketing)/      # Landing, about, pricing
│       │   │   ├── page.tsx
│       │   │   └── about/
│       │   │
│       │   ├── (content)/        # Reading experience
│       │   │   ├── read/
│       │   │   │   └── [book]/[chapter]/page.tsx
│       │   │   ├── characters/
│       │   │   └── lore/
│       │   │
│       │   ├── (app)/            # Authenticated app
│       │   │   ├── chat/
│       │   │   ├── create/
│       │   │   ├── discover/
│       │   │   └── profile/
│       │   │
│       │   └── api/              # API routes
│       │       ├── ai/
│       │       ├── auth/
│       │       └── webhooks/
│       │
│       ├── content/              # MDX content (CAN USE OBSIDIAN!)
│       │   ├── books/
│       │   │   └── book-1/
│       │   │       ├── chapters/
│       │   │       │   ├── 01-eye-of-wolf.mdx
│       │   │       │   └── 02-healers-touch.mdx
│       │   │       ├── characters/
│       │   │       │   ├── arion.mdx
│       │   │       │   └── mera.mdx
│       │   │       └── locations/
│       │   └── lore/
│       │
│       ├── components/
│       ├── lib/
│       ├── public/
│       └── package.json
│
├── packages/
│   ├── ui/                       # Shared components
│   ├── database/                 # Convex/Supabase
│   ├── ai/                       # AI integrations
│   └── config/                   # Configs
│
└── .claude/                      # Claude Code agents

📝 Content in Next.js (The Right Way)

Use Next.js Content Collections

// lib/content.ts
import fs from 'fs'
import path from 'path'
import matter from 'gray-matter'
import { compileMDX } from 'next-mdx-remote/rsc'

const CONTENT_PATH = path.join(process.cwd(), 'content')

export async function getChapter(book: string, slug: string) {
  const filePath = path.join(CONTENT_PATH, 'books', book, 'chapters', `${slug}.mdx`)
  const source = fs.readFileSync(filePath, 'utf8')

  const { content, data } = matter(source)

  const { content: mdxContent } = await compileMDX({
    source: content,
    options: { parseFrontmatter: true }
  })

  return {
    slug,
    metadata: data,
    content: mdxContent
  }
}

export async function getAllChapters(book: string) {
  const chaptersPath = path.join(CONTENT_PATH, 'books', book, 'chapters')
  const files = fs.readdirSync(chaptersPath)

  return Promise.all(
    files
      .filter(f => f.endsWith('.mdx'))
      .map(f => getChapter(book, f.replace('.mdx', '')))
  )
}

Reading Page (Server Component)

// app/(content)/read/[book]/[chapter]/page.tsx
import { getChapter, getAllChapters } from '@/lib/content'
import { notFound } from 'next/navigation'

export async function generateStaticParams() {
  const chapters = await getAllChapters('book-1')
  return chapters.map(chapter => ({
    book: 'book-1',
    chapter: chapter.slug
  }))
}

export default async function ChapterPage({
  params
}: {
  params: { book: string; chapter: string }
}) {
  const chapter = await getChapter(params.book, params.chapter)

  if (!chapter) notFound()

  return (
    <article className="prose prose-lg dark:prose-invert max-w-4xl mx-auto">
      <h1>{chapter.metadata.title}</h1>
      <div>{chapter.content}</div>
    </article>
  )
}

YOU CAN STILL USE OBSIDIAN!

Your Workflow:
1. Open Obsidian vault at apps/web/content/
2. Write chapters in MDX
3. Git commit
4. Push to GitHub
5. Vercel auto-deploys
6. Done!

Obsidian Config:

// apps/web/content/.obsidian/app.json
{
  "attachmentFolderPath": "../public/images",
  "useMarkdownLinks": true
}

You get:

  • ✅ Obsidian graph view
  • ✅ Obsidian plugins
  • ✅ Markdown files in Next.js
  • ✅ One deployment pipeline

💰 Cost Comparison (Realistic)

Simple Architecture (Next.js on Vercel)

Year 1 (1k users, 100k pageviews/mo):

  • Vercel Pro: $20/mo
  • Convex Free Tier: $0
  • Clerk Free Tier: $0
  • Lemon Squeezy fees: ~$20/mo
  • Total: $40/mo ($480/year)

At Scale (10k users, 1M pageviews/mo):

  • Vercel Pro: $20/mo (still under limits)
  • Convex Hobby: $25/mo
  • Clerk Pro: $25/mo
  • Lemon Squeezy fees: ~$100/mo
  • Total: $170/mo ($2,040/year)

When you hit 5M+ pageviews:

  • Consider migrating reading experience to Astro/Cloudflare
  • But you'll have revenue by then to justify the complexity

🚀 The Simple Stack (Final Answer)

┌─────────────────────────────────────────┐
│         ARCANEA (ALL IN ONE)            │
├─────────────────────────────────────────┤
│                                         │
│  FRAMEWORK: Next.js 16                  │
│  ├─ Content: MDX files (can use Obsidian)│
│  ├─ Reading: Static pages (ISR)        │
│  ├─ App: Dynamic features              │
│  └─ API: Serverless functions          │
│                                         │
│  DATABASE: Convex                       │
│  ├─ Users, creations, messages         │
│  ├─ Real-time subscriptions            │
│  └─ TypeScript-first                   │
│                                         │
│  AUTH: Clerk                            │
│  ├─ Social login                        │
│  ├─ User management                     │
│  └─ Org support (future)                │
│                                         │
│  STYLING: Tailwind + shadcn/ui         │
│  ├─ Magic UI (animations)              │
│  ├─ Aceternity (hero sections)         │
│  └─ Custom cosmic components           │
│                                         │
│  AI: Claude API + MCP                   │
│  ├─ Chat with Luminors                  │
│  ├─ Content generation                  │
│  └─ Agent workflows                     │
│                                         │
│  PAYMENTS: Lemon Squeezy                │
│  ├─ Subscriptions                       │
│  ├─ Tax handling                        │
│  └─ International support               │
│                                         │
│  HOSTING: Vercel                        │
│  ├─ Edge functions                      │
│  ├─ Image optimization                  │
│  └─ Analytics                           │
│                                         │
│  DOMAIN: arcanea.ai                     │
│  ├─ / (marketing)                       │
│  ├─ /read/... (books)                   │
│  └─ /app/... (platform)                 │
│                                         │
└─────────────────────────────────────────┘

✅ What This Gives You

For Writers (You)

  • ✅ Write in Obsidian (if you want)
  • ✅ OR write directly in VS Code
  • ✅ OR use any MDX editor
  • ✅ Git version control
  • ✅ See changes deployed in 60 seconds

For Readers

  • ✅ Fast page loads (Next.js static pages)
  • ✅ Beautiful reading experience
  • ✅ Can share chapters easily
  • ✅ Works on all devices

For Users

  • ✅ Chat with AI Luminors
  • ✅ Create and share content
  • ✅ Community features
  • ✅ Subscribe to premium

For Developers (You)

  • ✅ ONE codebase to maintain
  • ✅ ONE deployment to manage
  • ✅ Fast iteration cycle
  • ✅ Full React ecosystem
  • ✅ Great DX (Vercel + Next.js)

🔧 Implementation (Simple)

Week 1: Foundation

# 1. Create Next.js app
npx create-next-app@latest arcanea-web --typescript --tailwind --app

# 2. Add dependencies
npm install convex @clerk/nextjs
npm install next-mdx-remote gray-matter
npm install @lemonsqueezy/lemonsqueezy.js

# 3. Add shadcn/ui
npx shadcn-ui@latest init
npx shadcn-ui@latest add button input card dialog

# 4. Set up Convex
npx convex dev

# 5. Set up Clerk
# Add API keys to .env.local

# 6. Deploy to Vercel
vercel

Week 2: Content + Chat

# 1. Create content structure
mkdir -p content/books/book-1/chapters
touch content/books/book-1/chapters/01-eye-of-wolf.mdx

# 2. Build reading pages
# app/(content)/read/[book]/[chapter]/page.tsx

# 3. Build chat interface
# app/(app)/chat/[luminor]/page.tsx

# 4. Deploy
git push
# Vercel auto-deploys

Week 3: Community + Creation

# Build creation tools
# Build discovery feed
# Build user profiles
# Deploy

Week 4: Payments + Premium

# Integrate Lemon Squeezy
# Build subscription flow
# Premium content gating
# Deploy

📊 When to Consider Splitting

Stay with monolith UNTIL:

  • 5M+ page views/month
  • $10k+ MRR
  • 50k+ users
  • Page load performance becomes critical
  • Vercel bills > $500/mo

Then consider:

  • Moving reading experience to Astro/Cloudflare
  • Keeping app features in Next.js/Vercel
  • But you'll have revenue to justify the complexity

🎯 The Honest Answer

Question: Is it easier to have everything in Vercel?

Answer: YES, absolutely.

For early stage (where you are now):

  • ✅ Start with Next.js monolith on Vercel
  • ✅ Use MDX for content (can still use Obsidian)
  • ✅ Build everything in one place
  • ✅ Ship fast, iterate fast
  • ✅ Optimize when it actually matters

The hybrid architecture is premature optimization.

You need to:

  1. ✅ Ship the platform
  2. ✅ Get users
  3. ✅ Prove the concept
  4. ✅ Generate revenue

THEN worry about:

  • Splitting into microservices
  • Optimizing costs
  • Edge deployment strategies

💡 The Revised Recommendation

DO NOW: Simple Next.js Monolith

// This is enough for v1:
apps/
└── web/                 # Next.js 16
    ├── app/
    │   ├── (marketing)/
    │   ├── (content)/   # MDX pages
    │   ├── (app)/       # Chat, create, discover
    │   └── api/
    ├── content/         # MDX files (Obsidian-friendly)
    ├── components/
    └── lib/

Ship in 2 weeks.

DO LATER: Optimize if Needed

// Only if you hit scale problems:
apps/
├── content/             # Astro (reading)
└── platform/            # Next.js (app)

Wait until revenue justifies complexity.

🚀 Tomorrow's Prompt (Simplified)

Hey Claude! Let's build Arcanea as a Next.js monolith.

Context:
- Read /mnt/c/Users/Frank/Arcanea/ARCANEA_SIMPLE_ARCHITECTURE.md

Today's Goal: Foundation + First Features

Phase 1: Setup (2 hours)
1. Create Next.js 16 app with TypeScript + Tailwind
2. Add Convex for database
3. Add Clerk for auth
4. Add shadcn/ui components
5. Deploy to Vercel

Phase 2: Content (2 hours)
1. Set up content/ folder structure
2. Create MDX chapter system
3. Build reading page
4. Write first chapter
5. Deploy

Phase 3: Chat (2 hours)
1. Build chat interface
2. Integrate Claude API
3. Create Luminor personality (Melodia)
4. Test conversation flow
5. Deploy

Let's start with Phase 1. Show me the exact commands.

✨ Summary

You were right to question the complexity.

The hybrid architecture was technically optimal but operationally complex.

For getting Arcanea shipped, the simple monolith is better:

  • ✅ Faster to build
  • ✅ Easier to maintain
  • ✅ Still performant enough
  • ✅ Can optimize later when needed

Ship first. Optimize when revenue justifies it.

This is the pragmatic way. 🚀