# ADR 0001: Technology Stack

**Status**: ✅ Accepted
**Date**: 2025-12-11
**Deciders**: Development team + Client requirements

---

## Context

We need to build a hypermodern, performant marketing site for 1000planets.cloud that:
- Loads fast and ranks well (SEO critical)
- Supports future CMS integration for blog/case studies
- Can be self-hosted on nexus-vector
- Enables rapid iteration and content updates
- Maintains spec-kit compliance
- Scales to support agency partner spin-offs

---

## Decision

### Core Framework: **Next.js 14 (App Router)**

**Rationale**:
- **Performance**: Built-in optimization (image, font, code splitting)
- **SEO**: Server-side rendering, meta tag management
- **Flexibility**: Can serve static pages OR dynamic content
- **Developer Experience**: TypeScript support, hot reload, great docs
- **Ecosystem**: Massive community, proven at scale
- **Self-hosting**: Can deploy anywhere (Docker, VPS, etc.)

**Alternatives Considered**:
- **Astro**: Great for content-heavy sites, but less flexible for future interactive features
- **Vanilla React**: More control but need to build everything from scratch
- **Remix**: Excellent but smaller ecosystem

---

### Styling: **Tailwind CSS + shadcn/ui**

**Rationale**:
- **Tailwind CSS**: Utility-first, rapid development, consistent design system
- **shadcn/ui**: Beautifully designed components matching Linear/Vercel aesthetic
- **Dark/Light Mode**: Built-in support for theme switching
- **Customization**: Full control over design tokens (colors, spacing, typography)
- **Performance**: Only ships CSS actually used (tree-shaking)

---

### CMS: **Sanity.io**

**Rationale**:
- **Developer-Friendly**: Git-like workflow, version control for content
- **Flexible Schema**: Can model any content structure
- **Real-Time**: Live preview of content changes
- **Media Management**: Handles images, videos, files
- **Free Tier**: Generous limits for early stage
- **Self-Hosted Option**: Can run Sanity Studio anywhere

**Alternatives Considered**:
- **Contentful**: More enterprise-focused, higher cost
- **Strapi**: Self-hosted but heavier infrastructure
- **MDX Files**: Simple but no non-technical user UI

---

### Deployment: **Docker + nexus-vector (Self-Hosted)**

**Rationale**:
- **Client Requirement**: Must be self-hosted on nexus-vector
- **Docker**: Consistent environments, easy to replicate
- **Nginx Reverse Proxy**: Handle SSL, routing, caching
- **CI/CD**: Can automate with Git hooks or GitHub Actions
- **Cost**: No third-party hosting fees

**Deployment Stack**:
```
nexus-vector (216.158.230.94)
├── Docker Container: next-app
│   ├── Next.js 14 production build
│   ├── Node.js 18+ runtime
│   └── Port: 3000 (internal)
├── Nginx Reverse Proxy
│   ├── SSL/TLS (Let's Encrypt)
│   ├── Domain: 1000planets.cloud
│   └── Port: 443 (external)
└── Sanity Studio (optional separate container)
```

---

### Analytics: **Plausible (Primary) + Google Analytics (Optional)**

**Rationale**:
- **Plausible**: Privacy-focused, GDPR-compliant, lightweight
- **Google Analytics**: Optional for deeper insights
- **No A/B Testing** (initially): Keep it simple, iterate based on qualitative feedback

---

### Additional Tools

| Tool | Purpose | Rationale |
|------|---------|-----------|
| **TypeScript** | Type safety | Catch errors early, better DX |
| **Framer Motion** | Animations | Smooth, performant animations |
| **React Hook Form** | Forms | Trial signup, newsletter, contact |
| **Zod** | Validation | Type-safe form validation |
| **Resend** | Transactional email | Modern, developer-friendly |

---

## Consequences

### Positive
✅ Fast development velocity (proven stack)
✅ Excellent SEO out of the box
✅ Future-proof (can add features incrementally)
✅ Self-hosted (full control, no vendor lock-in)
✅ Spec-kit compliant (easy to document, test, deploy)

### Negative
⚠️ Requires Node.js runtime (vs pure static)
⚠️ Need to manage Docker containers
⚠️ Sanity.io adds external dependency (but has self-hosted option)

### Mitigations
- Use Docker Compose for easy container management
- Set up automated backups for Sanity content
- Document deployment process thoroughly
- Create rollback procedures

---

## Implementation Plan

1. ✅ Initialize Next.js 14 project with TypeScript
2. ✅ Configure Tailwind CSS + shadcn/ui
3. ✅ Set up Sanity.io project and schema
4. ✅ Create Docker configuration
5. ✅ Set up deployment pipeline
6. ✅ Configure analytics (Plausible)
7. ✅ Test on nexus-vector before launch

---

## References

- [Next.js Documentation](https://nextjs.org/docs)
- [Tailwind CSS](https://tailwindcss.com)
- [shadcn/ui](https://ui.shadcn.com)
- [Sanity.io](https://www.sanity.io)
- [Plausible Analytics](https://plausible.io)