Skip to content
FSS Knowledge Base

Web Development Guidelines

Section titled “Web Development Guidelines”

Core Architecture Stack

Section titled “Core Architecture Stack”
  • Site Framework: Astro (latest) for static content and blogs
  • Components: Svelte for interactive components
  • UI Library: Shadcn-Svelte with Tailwind CSS v4
  • Design System: CSS variables + Utopia fluid responsive design
  • Content: Markdown (.md) or MDX (.mdx) for blog content

Frontend Development Standards

Section titled “Frontend Development Standards”

Project Structure

Section titled “Project Structure”
project/
├── src/
│   ├── pages/          # Astro pages
│   ├── components/     # Svelte components
│   ├── layouts/        # Astro layouts
│   ├── content/        # Markdown content
│   └── styles/         # Global CSS + design tokens
├── public/             # Static assets
├── .astro/            # Astro build cache
└── astro.config.mjs    # Astro configuration

Component Development

Section titled “Component Development”
  • Svelte Components: Use Svelte 5 with runes syntax
  • Props: Always type props with TypeScript
  • Styling: Use Tailwind classes, CSS variables for theming
  • Accessibility: ARIA labels, semantic HTML, keyboard navigation
  • Performance: Lazy load images, minimize bundle size

Design System Implementation

Section titled “Design System Implementation”
  • CSS Variables: Define all design tokens (colors, spacing, typography) as CSS custom properties
  • Fluid Typography: Use Utopia.fyi tools for responsive typography scales
  • Color Themes: Support light/dark modes using CSS variables
  • Component Variants: Use class:name={condition} pattern in Svelte

Content Management

Section titled “Content Management”
  • CMS: Decap CMS for blog content management
  • Internationalization: Built-in i18n support for multi-language content
  • SEO: Automatic meta tags, structured data, sitemap generation
  • Image Optimization: Use Astro’s built-in image optimization

Backend & Database Standards

Section titled “Backend & Database Standards”

Database

Section titled “Database”
  • Primary: MariaDB for direct EspoCRM and Sendy integration
  • Alternative: PostgreSQL with Supabase for modern projects
  • Local Development: SQLite with proper migration path to production
  • ORM: Prisma for type-safe database access

API Development

Section titled “API Development”
  • REST APIs: Follow RESTful conventions
  • Authentication: Supabase Auth or EspoCRM Portal
  • Error Handling: Consistent error response format
  • Rate Limiting: Implement for all public endpoints
  • Documentation: OpenAPI/Swagger for all endpoints

Server-Side Rendering

Section titled “Server-Side Rendering”
  • Astro SSR: Enable for dynamic content and user authentication
  • Edge Functions: Use Cloudflare Workers for serverless functions
  • Caching: Implement appropriate cache headers and strategies

Deployment & Hosting

Section titled “Deployment & Hosting”

Frontend Hosting

Section titled “Frontend Hosting”
  • Primary: Cloudflare Pages for unbeatable performance
  • Alternative: Vercel for Jamstack hosting
  • CDN: Leverage Cloudflare’s global network
  • Build: Automatic builds from Git commits

Backend Hosting

Section titled “Backend Hosting”
  • Managed VPS: Cloudways on DigitalOcean Toronto
  • PHP Applications: EspoCRM, Sendy on LAMP stack
  • Node.js: For Astro SSR and APIs
  • Database: MariaDB on same VPS for performance

DevOps Pipeline

Section titled “DevOps Pipeline”
  • CI/CD: GitHub Actions for automated testing and deployment
  • Environment Variables: Secure management via platform built-ins
  • Secrets: Doppler for centralized secret management
  • Monitoring: Uptime Kuma for service monitoring

Performance & Optimization

Section titled “Performance & Optimization”

Core Web Vitals

Section titled “Core Web Vitals”
  • LCP: Optimize images, lazy loading, critical resource hints
  • FID: Minimize JavaScript, defer non-critical scripts
  • CLS: Define image dimensions, avoid layout shifts
  • Target: All metrics in “Good” range (green)

Asset Optimization

Section titled “Asset Optimization”
  • Images: Use modern formats (WebP, AVIF), responsive images
  • CSS: Critical CSS inline, defer non-critical styles
  • JavaScript: Code splitting, tree shaking, minimal bundles
  • Fonts: Font display swap, preload critical fonts

Caching Strategy

Section titled “Caching Strategy”
  • Static Assets: Long cache headers (1 year)
  • HTML: Short cache with ETags
  • API Responses: Appropriate cache based on content type
  • CDN: Leverage Cloudflare’s caching capabilities

Security Implementation

Section titled “Security Implementation”

Frontend Security

Section titled “Frontend Security”
  • Content Security Policy: Strict CSP headers
  • HTTPS: Enforce SSL/TLS everywhere
  • Input Validation: Client-side validation + server-side verification
  • XSS Prevention: Escape all user content

Backend Security

Section titled “Backend Security”
  • Authentication: JWT tokens with refresh strategy
  • Authorization: Role-based access control (RBAC)
  • SQL Injection: Parameterized queries only
  • CORS: Strict CORS policy configuration
  • Rate Limiting: Prevent abuse of APIs

Integration Patterns

Section titled “Integration Patterns”

Third-Party Services

Section titled “Third-Party Services”
  • Email: Amazon SES via Sendy for bulk emails
  • Analytics: Plausible Analytics for privacy-first tracking
  • Forms: Web3Forms or Formspree for form handling
  • Payments: Stripe for payment processing
  • Search: Meilisearch for site search functionality

Automation Integration

Section titled “Automation Integration”
  • n8n: Workflow automation for data processing
  • Webhooks: Implement for real-time integrations
  • Cron Jobs: Server-side scheduling for maintenance tasks

Testing & Quality Assurance

Section titled “Testing & Quality Assurance”

Testing Strategy

Section titled “Testing Strategy”
  • Unit Tests: Vitest for component and utility testing
  • E2E Tests: Playwright for user flow testing
  • Performance: Lighthouse CI for performance regression
  • Accessibility: Axe-core for automated a11y testing

Code Quality

Section titled “Code Quality”
  • Linting: ESLint + Prettier for code consistency
  • Type Safety: TypeScript for all JavaScript code
  • Bundle Analysis: Analyze and optimize bundle size
  • Performance Budgets: Set and enforce performance budgets

Documentation Standards

Section titled “Documentation Standards”
  • README: Setup, deployment, and contribution guidelines
  • Component Stories: Storybook for component documentation
  • API Docs: Generated from OpenAPI specifications
  • Architecture: Decision records (ADRs) for major decisions

IF ANY TASK IS NOT VERY CLEAR OR ADDITIONAL INFORMATION IS NEEDED OR EVEN WOULD BE HELPFUL, ALWAYS ASK. IT IS MUCH MORE EFFECTIVE TO BE 100% CLEAR ON WHAT IS EXPECTED FROM THE START.