oneie/one/knowledge/astro-effect-simple-architecture.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: Astro Effect Simple Architecture
dimension: knowledge
category: astro-effect-simple-architecture.md
tags: architecture, system-design
related_dimensions: events, things
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the knowledge dimension in the astro-effect-simple-architecture.md category.
  Location: one/knowledge/astro-effect-simple-architecture.md
  Purpose: Documents astro + effect.ts + shadcn: the simplest possible architecture
  Related dimensions: events, things
  For AI agents: Read this to understand astro effect simple architecture.
---

# Astro + Effect.ts + shadcn: The Simplest Possible Architecture

**START HERE:** This is the primary architecture document. Read this first before diving into complex patterns.

## Quick Reference Card

```
┌──────────────────────────────────────────────────────────────┐
│  The 4-Step Pattern (Layer 1 - Start Here!)                 │
├──────────────────────────────────────────────────────────────┤
│  1. Define Schema    → Zod validation in src/content/config  │
│  2. Create Content   → YAML/MD files in src/content/*        │
│  3. Query in Pages   → getCollection() in .astro files       │
│  4. Render with UI   → shadcn components with client:load    │
├──────────────────────────────────────────────────────────────┤
│  🛑 STOP HERE IF: You're building docs, blogs, marketing,   │
│     simple dashboards, or any content-driven site            │
└──────────────────────────────────────────────────────────────┘

Need more? Add layers progressively:

┌──────────────────────────────────────────────────────────────┐
│  Layer 2: Effect.ts Services (Optional)                      │
├──────────────────────────────────────────────────────────────┤
│  Add when you need: Validation, business logic, error types  │
│  🛑 STOP HERE IF: No database or auth required              │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  Layer 3: REST API Backend (Rarely Needed)                   │
├──────────────────────────────────────────────────────────────┤
│  Add when you need: Database, authentication, payments       │
│  🛑 STOP HERE: You've reached the final layer              │
└──────────────────────────────────────────────────────────────┘
```

## Core Principle: Start Simple, Add Complexity Only When Needed

**Reality Check:** 80% of apps need only Layer 1. Most of the rest stop at Layer 2. Very few need Layer 3.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│  ASTRO PAGES (.astro files)                             │
│  - File-based routing                                   │
│  - Render content collections                           │
│  - Server-side rendering                                │
│  └─→ Props to React components                          │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  CONTENT COLLECTIONS (type-safe structured data)        │
│  - Blog posts, docs, products, teams, etc               │
│  - Zod schemas for validation                           │
│  - Query with type safety                               │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  SHADCN COMPONENTS (React)                              │
│  - Button, Card, Dialog, Form, etc                      │
│  - Receive data as props                                │
│  - client:load for interactivity                        │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  EFFECT.TS SERVICES (business logic)                    │
│  - Validation                                           │
│  - Transformation                                       │
│  - Error handling                                       │
│  └─→ Called from pages or components                    │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  OPTIONAL: REST API (backend)                           │
│  - Database persistence                                │
│  - Authentication                                       │
│  - Complex operations                                   │
└─────────────────────────────────────────────────────────┘
```

## Layer 1: The Basic Pattern (Start Here!)

**When to use:** Content-driven sites, documentation, marketing pages, blogs, simple dashboards

**When to stop:** If you don't need validation, API calls, or complex business logic - you're done!

### The 4-Step Pattern

1. **Define Schema** (Zod validation)
2. **Create Content** (YAML/Markdown files)
3. **Query in Pages** (`getCollection()`)
4. **Render with shadcn** (beautiful UI components)

### Complete Example: Teams Feature

#### Step 1: Define Schema

```typescript
// src/content/config.ts
import { defineCollection, z } from "astro:content";

const teamsCollection = defineCollection({
  type: "data",
  schema: z.object({
    name: z.string(),
    description: z.string(),
    members: z.array(z.string()).default([]),
    status: z.enum(["active", "archived"]).default("active"),
    owner: z.string(),
  }),
});

const docsCollection = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    description: z.string(),
    category: z.enum(["getting-started", "guide", "api"]),
  }),
});

export const collections = {
  teams: teamsCollection,
  docs: docsCollection,
};
```

#### Step 2: Create Content

```yaml
# src/content/teams/engineering.yaml
name: Engineering
description: Core platform development
members:
  - alice
  - bob
  - charlie
owner: alice
status: active
```

#### Step 3: Query in Pages

```astro
---
// src/pages/teams/index.astro
import Layout from "@/layouts/Layout.astro";
import { getCollection } from "astro:content";
import TeamCard from "@/components/TeamCard.tsx";

// Get all teams - TypeScript knows the shape!
const teams = await getCollection("teams");
const sortedTeams = teams.sort((a, b) =>
  a.data.name.localeCompare(b.data.name)
);
---

<Layout title="Teams">
  <div class="container py-8">
    <h1 class="text-4xl font-bold mb-8">Teams</h1>
    <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
      {sortedTeams.map(team => (
        <TeamCard team={team.data} client:load />
      ))}
    </div>
  </div>
</Layout>
```

#### Step 4: Render with shadcn Components

```tsx
// src/components/TeamCard.tsx
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";

export function TeamCard({ team }) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>{team.name}</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <p className="text-sm text-gray-600">{team.description}</p>

        <div className="flex gap-2">
          <Badge>{team.status}</Badge>
          <span className="text-sm text-gray-500">{team.members.length} members</span>
        </div>

        <Button asChild className="w-full">
          <a href={`/teams/${team.name}`}>View Team</a>
        </Button>
      </CardContent>
    </Card>
  );
}
```

**That's Layer 1!** No database, no stores, no state management. Just:
- Schema → Content → Query → Render

**STOP HERE IF:** You're building content-driven sites (docs, blogs, marketing, simple dashboards)

---

## Layer 2: Add Effect.ts Services (Optional!)

**When to add:** You need validation, business logic, error handling, or data transformation

**When to stop:** If you don't need API calls or database persistence - you're done!

### Why Effect.ts?

- Type-safe errors (no throwing exceptions)
- Composable business logic
- Clean separation of concerns
- Excellent for validation and data transformation

### Example: Add Validation

```typescript
// src/lib/services/teamService.ts
import { Effect } from "effect";

export type TeamError =
  | { _tag: "ValidationError"; message: string }
  | { _tag: "NotFoundError"; id: string };

export const validateTeamName = (name: string): Effect.Effect<string, TeamError> =>
  Effect.gen(function* () {
    if (!name?.trim()) {
      return yield* Effect.fail({
        _tag: "ValidationError",
        message: "Team name required",
      });
    }
    if (name.length < 2) {
      return yield* Effect.fail({
        _tag: "ValidationError",
        message: "Name must be at least 2 characters",
      });
    }
    return name.trim();
  });

export const validateTeam = (team: unknown): Effect.Effect<Team, TeamError> =>
  Effect.gen(function* () {
    // Run validation
    // Return validated team or error
  });
```

Use in pages:

```astro
---
import { validateTeamName } from "@/lib/services/teamService";
import { Effect } from "effect";

// Server-side: run Effect immediately
const result = await Effect.runPromise(
  validateTeamName(teamName)
);

if (result instanceof Error) {
  // Handle error
}
---

<!-- Render result -->
```

**STOP HERE IF:** You don't need database persistence, authentication, or external APIs

---

## Layer 3: Add REST API (Optional!)

**When to add:** You need database persistence, user authentication, external API integrations, or real-time updates

**This is the last layer!** Most apps never need this.

### When You Actually Need a Backend

- User authentication and sessions
- Database persistence (PostgreSQL, MySQL, MongoDB)
- Payment processing
- Real-time features (WebSockets)
- Complex server-side operations
- External API orchestration

### Example: Simple API with Hono

```typescript
// backend/src/routes/teams.ts
import { Hono } from "hono";

const app = new Hono();

app.get("/teams", async (c) => {
  // Query database
  return c.json({ data: [...] });
});

app.post("/teams", async (c) => {
  // Validate, save, return
  return c.json({ data: {...} }, 201);
});
```

### Call API from Astro

```astro
---
// Server-side fetch (no JavaScript sent to browser)
const res = await fetch("https://your-api.com/api/teams");
const teams = await res.json();
---

<!-- Render teams -->
```

---

## Decision Tree: Which Layers Do You Need?

```
START: Do you need dynamic data?
├─ NO → Layer 1 only (Astro + Content Collections) ✅ DONE
└─ YES → Continue...

    Do you need validation or business logic?
    ├─ NO → Layer 1 only ✅ DONE
    └─ YES → Add Layer 2 (Effect.ts services)

        Do you need database or auth?
        ├─ NO → Stop at Layer 2 ✅ DONE
        └─ YES → Add Layer 3 (REST API backend)
```

**Reality Check:** 80% of apps need only Layer 1. Most of the rest stop at Layer 2.

---

## Complete Example: Simple Teams App

### Directory Structure

```
src/
├── pages/
│   ├── index.astro           # Home
│   ├── teams/
│   │   ├── index.astro       # List teams
│   │   └── [name].astro      # Team detail
│   └── docs/
│       └── [...slug].astro   # Documentation pages
│
├── content/
│   ├── config.ts             # Content collection schemas
│   ├── teams/
│   │   ├── engineering.yaml
│   │   └── marketing.yaml
│   └── docs/
│       ├── getting-started.md
│       └── api.md
│
├── components/
│   ├── TeamCard.tsx          # shadcn-based component
│   ├── TeamDetail.tsx
│   └── ui/                   # shadcn components (installed)
│       ├── button.tsx
│       ├── card.tsx
│       └── badge.tsx
│
└── lib/
    └── services/
        └── teamService.ts    # Effect.ts services
```

### Page: List Teams

```astro
---
// src/pages/teams/index.astro
import Layout from "@/layouts/Layout.astro";
import { getCollection } from "astro:content";
import TeamCard from "@/components/TeamCard.tsx";

const teams = await getCollection("teams");
const sortedTeams = teams.sort((a, b) =>
  a.data.name.localeCompare(b.data.name)
);
---

<Layout title="Teams">
  <div class="container py-12">
    <h1 class="text-4xl font-bold mb-8">Teams</h1>

    <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
      {sortedTeams.map(team => (
        <TeamCard team={team.data} client:load />
      ))}
    </div>
  </div>
</Layout>
```

### Page: Team Detail

```astro
---
// src/pages/teams/[name].astro
import Layout from "@/layouts/Layout.astro";
import { getCollection } from "astro:content";
import TeamDetail from "@/components/TeamDetail.tsx";

export async function getStaticPaths() {
  const teams = await getCollection("teams");
  return teams.map(team => ({
    params: { name: team.id },
    props: { team },
  }));
}

const { team } = Astro.props;
---

<Layout title={team.data.name}>
  <div class="container py-12">
    <a href="/teams" class="text-blue-500 hover:underline mb-4">← Back</a>
    <TeamDetail team={team.data} client:load />
  </div>
</Layout>
```

### Component: Team Detail (Interactive)

```tsx
// src/components/TeamDetail.tsx
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";
import { useState } from "react";

export function TeamDetail({ team }) {
  const [showMembers, setShowMembers] = useState(false);

  return (
    <Card>
      <CardHeader>
        <div className="flex justify-between items-start">
          <div>
            <CardTitle className="text-3xl">{team.name}</CardTitle>
            <p className="text-gray-600 mt-2">{team.description}</p>
          </div>
          <Badge>{team.status}</Badge>
        </div>
      </CardHeader>
      <CardContent className="space-y-6">
        <div>
          <h3 className="font-semibold mb-2">Members ({team.members.length})</h3>
          <button
            onClick={() => setShowMembers(!showMembers)}
            className="text-blue-500 hover:underline"
          >
            {showMembers ? "Hide" : "Show"} members
          </button>

          {showMembers && (
            <ul className="list-disc list-inside mt-2">
              {team.members.map(member => (
                <li key={member}>{member}</li>
              ))}
            </ul>
          )}
        </div>
      </CardContent>
    </Card>
  );
}
```

## Quick Start Commands

### Generate a New Feature

```bash
# Generate complete feature (schema + content + pages + components)
npx oneie generate:feature teams

# This creates:
# 1. Content collection schema (src/content/config.ts)
# 2. Sample YAML files (src/content/teams/*)
# 3. List and detail pages (src/pages/teams/*)
# 4. shadcn components (src/components/TeamCard.tsx)
# 5. Effect.ts service (src/lib/services/teamService.ts)
```

### Add shadcn Components

```bash
# Add individual components as needed
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add badge
npx shadcn@latest add dialog
npx shadcn@latest add form
```

## Why This Architecture Works

| Layer | What It Does | When You Need It |
|-------|-------------|------------------|
| **Layer 1: Astro + Content** | Static content, routing, SSR | Always (80% stop here) |
| **Layer 2: Effect.ts** | Validation, business logic | Sometimes (15% stop here) |
| **Layer 3: REST API** | Database, auth, persistence | Rarely (5% need this) |

### Why It Matters

This architecture matters because it fundamentally changes how we think about building web applications in an AI-native world:

**For Developers:**
- **98% AI Code Generation** - Simple, predictable patterns mean AI assistants like Claude can generate correct code with near-perfect accuracy
- **100x Faster Development** - By feature #100, you're building in hours what traditionally takes days
- **Zero Context Switching** - No jumping between frontend/backend mental models. Content collections ARE your database.
- **Instant Onboarding** - New team members understand the entire system in hours, not weeks
- **Technical Credit Accumulates** - Each feature you build makes the next one easier (opposite of technical debt)

**For Businesses:**
- **12x Cheaper at Scale** - Feature #100 costs less than feature #1 due to pattern convergence
- **Zero Breaking Changes** - Extend infinitely without migrations or downtime
- **Lightning Performance** - Perfect Lighthouse scores by default (90+ across all metrics)
- **SEO Dominance** - Server-side rendering means search engines see everything instantly
- **Future-Proof** - When frameworks change, your content stays stable

**For End Users:**
- **Sub-2-Second Load Times** - Static generation + islands architecture = instant page loads
- **Mobile-First** - Optimized bundle sizes mean fast experiences on any device
- **Accessibility** - shadcn/ui components are WCAG-compliant out of the box
- **Offline-Ready** - Progressive enhancement means core content works without JavaScript

**The Economic Reality:**
Traditional architectures create exponential complexity (technical debt). This architecture creates exponential simplicity (technical credit). After 100 features, traditional apps slow to a crawl. Apps built with this architecture accelerate.

**The AI Reality:**
Pattern convergence is everything. When AI sees 3 patterns repeated 1000x, it achieves 98% accuracy. When it sees 1000 unique patterns, accuracy drops to 30%. This architecture was designed for the AI era.

**The Philosophical Shift:**
Stop building applications. Start modeling reality. Content collections model your domain (products, courses, teams). The 6-dimension ontology models universal structure (groups, people, things, connections, events, knowledge). When you model reality instead of features, the system becomes infinitely extensible.

### Key Benefits

| Benefit | Why It Matters |
|---------|----------------|
| **No stores** | Content collections are the source of truth - zero state management complexity |
| **No complex state** | Data flows down as props - React without the React chaos |
| **Progressive complexity** | Add layers only when needed - never over-engineer |
| **Type-safe everywhere** | Zod + TypeScript + Effect - catch errors at compile time, not production |
| **Minimal JavaScript** | `client:load` only where needed - 90% of your app ships as HTML |
| **SEO-friendly** | Server-side rendering by default - Google sees everything instantly |
| **Fast by default** | Static generation + islands - Lighthouse 90+ without trying |
| **Agent-friendly** | Simple patterns, clear layers - AI generates code with 98% accuracy |

## Real World: Blog + Teams + Documentation

```astro
---
// src/pages/index.astro

// Get all content
const teams = await getCollection("teams");
const blogPosts = await getCollection("blog");
const docs = await getCollection("docs");

// Sort/filter on server
const latestPosts = blogPosts
  .sort((a, b) => b.data.date - a.data.date)
  .slice(0, 3);
---

<Layout title="Home">
  <Hero />

  <section class="py-12">
    <h2 class="text-3xl font-bold mb-6">Latest Blog Posts</h2>
    <div class="grid grid-cols-3 gap-4">
      {latestPosts.map(post => (
        <BlogCard post={post.data} client:load />
      ))}
    </div>
  </section>

  <section class="py-12">
    <h2 class="text-3xl font-bold mb-6">Our Teams</h2>
    <div class="grid grid-cols-3 gap-4">
      {teams.map(team => (
        <TeamCard team={team.data} client:load />
      ))}
    </div>
  </section>
</Layout>
```

## File Structure: Maximum Simplicity

```
src/
├── pages/                    # Routes (Astro SSR)
│   ├── index.astro
│   ├── teams/
│   │   ├── index.astro
│   │   └── [name].astro
│   ├── blog/
│   │   ├── index.astro
│   │   └── [...slug].astro
│   └── docs/
│       └── [...slug].astro
│
├── content/                  # Type-safe content
│   ├── config.ts            # Zod schemas
│   ├── teams/               # YAML data
│   ├── blog/                # Markdown posts
│   └── docs/                # Markdown docs
│
├── components/              # UI components
│   ├── TeamCard.tsx         # shadcn-based
│   ├── BlogCard.tsx
│   ├── DocLayout.tsx
│   └── ui/                  # shadcn components
│       ├── button.tsx
│       ├── card.tsx
│       └── ...
│
├── layouts/                 # Page templates
│   ├── Layout.astro
│   ├── BlogLayout.astro
│   └── DocLayout.astro
│
└── lib/
    └── services/            # Effect.ts logic
        ├── teamService.ts
        ├── blogService.ts
        └── ...
```

## The Philosophy

**Astro Content Collections** = Database (type-safe, versioned, simple)
**shadcn Components** = UI (beautiful, accessible, proven)
**Effect.ts Services** = Business Logic (type-safe errors, composable)
**Astro Pages** = Routes (server-rendering, clear structure)

No stores. No providers. No context. No Redux. No hooks hell.

Just:
1. Define schema (Zod)
2. Create content (YAML/Markdown)
3. Query content (Astro)
4. Pass to components (props)
5. Add business logic (Effect.ts)
6. Deploy (Cloudflare Pages)

**That's it. Everything you need. Nothing you don't.**

## Agent-Friendly

Agents can:
```typescript
// 1. Define schema
export const teamSchema = z.object({
  name: z.string(),
  description: z.string(),
  // ...
});

// 2. Create content
// Just drop YAML files in src/content/teams/

// 3. Render
// Use getCollection() in Astro pages

// 4. Add logic
// Write Effect.ts services

// 5. Deploy
// npm run build && wrangler pages deploy dist
```

Simple, predictable, extensible.

## Summary: The 3-Layer Architecture

```
┌─────────────────────────────────────────────────────────┐
│  Layer 1: ASTRO + CONTENT COLLECTIONS + SHADCN          │
│  → Schema → Content → Query → Render                    │
│  → Stop here for: Docs, blogs, marketing, dashboards    │
│  → 80% of apps need only this                           │
├─────────────────────────────────────────────────────────┤
│  Layer 2: ADD EFFECT.TS SERVICES                        │
│  → Validation, business logic, error handling           │
│  → Stop here for: Apps with complex logic but no DB     │
│  → 15% of apps stop here                                │
├─────────────────────────────────────────────────────────┤
│  Layer 3: ADD REST API BACKEND                          │
│  → Database, auth, payments, real-time                  │
│  → Stop here for: Full-stack apps                       │
│  → 5% of apps need this                                 │
└─────────────────────────────────────────────────────────┘
```

## Remember

1. **Start with Layer 1** - It's enough for most things
2. **Add Layer 2 only if needed** - Validation and business logic
3. **Add Layer 3 only if needed** - Database and authentication
4. **Don't over-engineer** - Complexity is the enemy

## Related Documentation

- **CLAUDE.md** - Root directory instructions for the platform
- **AGENTS.md** - AI agent coordination and rules
- **one/knowledge/ontology.md** - 6-dimension ontology (if using backend)
- **one/connections/workflow.md** - Development workflow
- **one/knowledge/architecture.md** - Complete architecture details

---

**Maximum simplicity. Maximum effectiveness. Start simple, grow as needed.**