Project Description
# Freelance Developer Brief — AI-Powered Astro Local SEO Site Generator
## Project Overview
We are looking for a highly capable developer to build a scalable local SEO website generation system using Astro.
This is NOT a standard website project.
The goal is to build a reusable SEO site generation engine that can:
* Generate complete local SEO websites
* Generate 30–100+ pages automatically
* Build internal linking automatically
* Generate schema automatically
* Handle image SEO automatically
* Use structured datasets/content
* Output ultra-fast static HTML websites
The framework must be reusable across many niches and cities.
Examples:
* plumbers
* electricians
* roofing
* paving
* tree felling
* locksmiths
* pool services
* etc.
---
# Preferred Tech Stack
Mandatory:
* Astro
* Tailwind CSS
* Node.js
* JSON datasets
* GitHub
Preferred:
* OpenAI API integration
* Claude API integration
* Markdown support
Hosting:
* Static HTML export
* Compatible with cPanel/shared hosting
* Cloudflare Pages compatibility is a bonus
---
# Main Goal
We want a reusable “Local SEO Website Generator System”.
The system should allow us to:
1. Input structured content/data
2. Generate pages automatically
3. Generate internal links automatically
4. Generate schema automatically
5. Build and export static websites
---
# Core Features Required
## 1 — Dynamic Routing
Need Astro dynamic routes such as:
```plaintext
/service/area/
```
Examples:
```plaintext
/plumber/sandton/
/plumber/randburg/
/blocked-drains/midrand/
```
Pages should generate automatically from datasets.
---
# 2 — Reusable SEO Components
Need reusable components including:
* Hero section
* FAQ section
* Nearby areas section
* Internal links section
* CTA section
* Reviews section
* Breadcrumbs
* Schema component
Must work across all niches.
---
# 3 — Internal Linking Engine
Very important.
The system must automatically:
* link nearby suburbs
* link related services
* generate silo links
* generate footer links
* update links automatically when pages are added
Example:
On:
```plaintext
/plumber/sandton/
```
Automatically link:
```plaintext
/plumber/randburg/
/blocked-drains/sandton/
/geyser-repair/sandton/
```
---
# 4 — SEO Automation
Need automatic generation of:
* meta titles
* meta descriptions
* canonical tags
* breadcrumbs
* sitemap.xml
* robots.txt
* schema markup
Required schema:
* LocalBusiness
* FAQPage
* BreadcrumbList
---
# 5 — Structured Content System
The system should preferably use:
* JSON
* Markdown
* CSV imports
Example data structure:
```json
{
"service": "plumber",
"area": "sandton",
"title": "Plumber Sandton",
"nearbyAreas": ["randburg", "bryanston"]
}
```
---
# 6 — Word Document Import System (Important)
We would like support for importing content from Word documents (.docx).
The system should ideally:
* extract text
* extract headings
* extract images
* extract captions
* structure content into pages
Optional AI enhancement features:
* rename image files SEO-friendly
* generate alt text
* generate image captions
* organize images into folders automatically
---
# 7 — AI Integration (Preferred)
Would like optional AI integrations for:
* H1 generation
* H2 generation
* FAQ generation
* metadata generation
* schema generation
* semantic optimization
Preferred APIs:
* OpenAI API
* Claude API
---
# 8 — Static Site Generation
The final output must be:
* pure static HTML
* lightweight
* SEO-first
* ultra-fast
The system should export a full `/dist/` folder ready for upload to hosting.
---
# 9 — Easy Content Editing
Very important.
We should be able to:
* add new pages later
* edit content later
* regenerate internal links automatically
* rebuild the site easily
The architecture should be:
* data-driven
* template-driven
* scalable
NOT manually hardcoded pages.
---
# 10 — Local Preview Workflow
Need local development workflow using:
```bash
npm run dev
npm run build
npm run preview
```
Must be easy to:
* preview locally
* build production version
* export final files
---
# Deliverables
We require:
* Full Astro framework
* Reusable architecture
* Dynamic routing system
* Internal linking engine
* SEO automation system
* Schema system
* Sitemap generation
* Example datasets
* Example generated pages
* Setup instructions
* Build instructions
* Deployment instructions
---
# Important Notes
We are NOT looking for:
* WordPress
* Elementor
* Divi
* drag/drop builders
* heavy CMS systems
We want:
* scalable architecture
* programmatic SEO system
* reusable framework
* static site generation
---
# Preferred Experience
Please include:
* Astro experience
* static site generation experience
* programmatic SEO experience
* Node.js automation experience
* AI integration experience
* GitHub profile
* examples of similar work
---
# Estimated Scope
Initial target:
* reusable framework
* first production-ready local SEO site
* approximately 30 pages
Future goal:
* scale framework across many niches/cities
---
# Budget Guidance
We are open to:
* fixed price
* milestone-based pricing
Please provide:
* estimated timeline
* estimated cost
* recommended architecture
* suggested improvements