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>
4.7 KiB
4.7 KiB
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
- ✅ Initialize Next.js 14 project with TypeScript
- ✅ Configure Tailwind CSS + shadcn/ui
- ✅ Set up Sanity.io project and schema
- ✅ Create Docker configuration
- ✅ Set up deployment pipeline
- ✅ Configure analytics (Plausible)
- ✅ Test on nexus-vector before launch