673007cc9f
- Completed client discovery questionnaire
- Created creative brief with mission, brand essence, and strategy
- ADR 0001: Tech stack (Next.js 14, Tailwind, Sanity, self-hosted)
- ADR 0002: Brand guidelines (colors, typography, voice, accessibility)
Key insights:
- Social impact mission: /month for single mothers and underserved communities
- Visual: Linear + Vercel aesthetic with semantic color system
- Target: Small business owners with high Google rankings but poor sites
- Primary CTA: 30-day free trial with domain pointing
Ready to build!
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
154 lines
4.7 KiB
Markdown
154 lines
4.7 KiB
Markdown
# 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)
|