Status: ✅ Production-Ready | 🤖 AI-Optimized | 💎 Catalyst-Integrated
Timeline: 12 Months from Start to Full Production
Cost: $0-50/month (personal use, free tier services)
- Quick Start - Tomorrow Evening Setup
- Project Architecture Overview
- Complete File Structure
- Phase 1: Core Setup (Week 1)
- Configuration Files
- Database Schemas
- API Design
- Frontend Templates
- Backend Templates
- 12-Month Implementation Roadmap
- Cost Breakdown
- AI-Optimization Guide
- GitHub account with Copilot subscription (with Claude Sonnet 4.5 enabled)
- Catalyst UI subscription credentials
- VSCode installed
- Node.js 18+ installed
- Python 3.11+ installed
- PostgreSQL 15+ installed (or Docker Desktop)
- Git installed
# 1. Create project directory and initialize
mkdir celestial-signs && cd celestial-signs
git init
# 2. Initialize spec-kit (required for SDD workflow)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init
# Select: GitHub Copilot as AI agent
# Select: Bash for script type
# 3. Clone starter repository structure
git checkout -b main
# 4. Install frontend dependencies
npx create-next-app@latest frontend --typescript --tailwind --app --no-src-dir
cd frontend
npm install @catalyst/ui three @react-three/fiber @react-three/drei cesium d3-celestial
# 5. Install backend dependencies
cd ..
mkdir backend && cd backend
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install --break-system-packages fastapi uvicorn sqlalchemy psycopg2-binary astroquery skyfield czml3 requests python-dotenv
# 6. Setup PostgreSQL with Docker (optional, easier)
cd ..
docker run --name celestial-db -e POSTGRES_PASSWORD=celestial2025 -e POSTGRES_DB=celestial_signs -p 5432:5432 -d postgis/postgis:15-3.3
# 7. Create initial project structure
mkdir -p {backend/{app/{api,core,db,models,services},tests},frontend/{app,components,lib,public},docs,docker,.github/workflows}
# 8. You're ready! Open in VSCode:
code .┌─────────────────────────────────────────────────────────────────┐
│ CELESTIAL SIGNS ARCHITECTURE │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ THREE.JS │ │ CESIUM.JS │ │ D3-CELESTIAL │ │
│ │ Solar System 3D │ │ Earth Dashboard │ │ Sky Maps 2D │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ ┌────────┴────────────────────┴─────────────────────┴────────┐ │
│ │ REACT + CATALYST UI FRONTEND │ │
│ │ (TypeScript, Tailwind CSS, Next.js 14) │ │
│ └────────────────────────────┬─────────────────────────────────┘ │
│ │ │
│ │ REST/WebSocket API │
│ │ │
│ ┌────────────────────────────┴─────────────────────────────────┐ │
│ │ FASTAPI BACKEND (Python) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Data Ingest │ │ Analysis │ │ API Server │ │ │
│ │ │ Services │ │ Engine │ │ Routes │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ └─────────┼──────────────────┼──────────────────┼───────────────┘ │
│ │ │ │ │
│ ┌─────────┴──────────────────┴──────────────────┴───────────────┐ │
│ │ POSTGRESQL + POSTGIS DATABASE │ │
│ │ ┌─────────────────┐ ┌──────────────────────────────┐ │ │
│ │ │ Scientific Data │ │ Theological Data Layer │ │ │
│ │ │ (Ephemeris, │ │ (Prophecies, Signs, PDS) │ │ │
│ │ │ Risks, Events) │ │ │ │ │
│ │ └─────────────────┘ └──────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ EXTERNAL DATA SOURCES │ │
│ │ JPL Horizons • JPL Sentry • USGS • NOAA • MPC • GMN │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
celestial-signs/
├── 📄 README.md # Project overview
├── 📄 .gitignore # Git ignore rules
├── 📄 docker-compose.yml # Multi-container Docker setup
├── 📄 IMPLEMENTATION_TIMELINE.md # Detailed 12-month roadmap
│
├── 📁 specify/ # Spec-Kit SDD workspace
│ ├── 📄 constitution.md # Project constitution (AI context)
│ ├── 📁 specs/ # Feature specifications
│ │ ├── 📁 solar-system-explorer/
│ │ ├── 📁 watchman-dashboard/
│ │ └── 📁 prophecy-engine/
│ └── 📁 tasks/ # Task breakdowns
│
├── 📁 frontend/ # Next.js 14 + React application
│ ├── 📄 package.json
│ ├── 📄 tsconfig.json
│ ├── 📄 next.config.js
│ ├── 📄 tailwind.config.ts
│ ├── 📄 .cursorrules # AI assistant rules
│ │
│ ├── 📁 app/ # Next.js App Router
│ │ ├── 📄 layout.tsx # Root layout with Catalyst
│ │ ├── 📄 page.tsx # Home page
│ │ ├── 📁 solar-system/
│ │ │ └── 📄 page.tsx # Module 1: 3D Explorer
│ │ ├── 📁 dashboard/
│ │ │ └── 📄 page.tsx # Module 2: Watchman Dashboard
│ │ ├── 📁 prophecy-codex/
│ │ │ └── 📄 page.tsx # Module 3: Prophecy Library
│ │ └── 📁 api/ # API routes (if needed)
│ │
│ ├── 📁 components/ # React components
│ │ ├── 📁 layout/
│ │ │ ├── 📄 Sidebar.tsx # TheSkyLive-style sidebar
│ │ │ ├── 📄 Navbar.tsx # Top navigation
│ │ │ └── 📄 Footer.tsx
│ │ ├── 📁 visualizations/
│ │ │ ├── 📄 SolarSystemViewer.tsx # Three.js wrapper
│ │ │ ├── 📄 EarthDashboard.tsx # Cesium.js wrapper
│ │ │ └── 📄 SkyMap.tsx # D3-Celestial wrapper
│ │ ├── 📁 alerts/
│ │ │ ├── 📄 AlertCard.tsx
│ │ │ └── 📄 AlertList.tsx
│ │ └── 📁 ui/ # Catalyst UI wrappers
│ │
│ ├── 📁 lib/ # Utilities & hooks
│ │ ├── 📄 api-client.ts # Backend API client
│ │ ├── 📄 three-helpers.ts # Three.js utilities
│ │ ├── 📄 cesium-helpers.ts # Cesium utilities
│ │ └── 📄 types.ts # TypeScript definitions
│ │
│ └── 📁 public/ # Static assets
│ ├── 📁 textures/ # Planetary textures
│ ├── 📁 data/ # Constellation GeoJSON
│ └── 📁 images/
│
├── 📁 backend/ # FastAPI Python application
│ ├── 📄 requirements.txt # Python dependencies
│ ├── 📄 pyproject.toml # Modern Python config
│ ├── 📄 .env.example # Environment template
│ ├── 📄 Dockerfile # Container definition
│ │
│ ├── 📁 app/
│ │ ├── 📄 main.py # FastAPI app entry
│ │ ├── 📄 config.py # Settings (Pydantic)
│ │ │
│ │ ├── 📁 api/ # API routes
│ │ │ ├── 📄 __init__.py
│ │ │ ├── 📁 v1/
│ │ │ │ ├── 📄 __init__.py
│ │ │ │ ├── 📄 ephemeris.py # /api/v1/ephemeris/*
│ │ │ │ ├── 📄 alerts.py # /api/v1/alerts/*
│ │ │ │ ├── 📄 prophecies.py # /api/v1/prophecies/*
│ │ │ │ └── 📄 dashboard.py # /api/v1/dashboard/*
│ │ │
│ │ ├── 📁 core/ # Core functionality
│ │ │ ├── 📄 __init__.py
│ │ │ ├── 📄 security.py # Auth (future)
│ │ │ └── 📄 logging.py # Logging config
│ │ │
│ │ ├── 📁 db/ # Database
│ │ │ ├── 📄 __init__.py
│ │ │ ├── 📄 session.py # SQLAlchemy session
│ │ │ ├── 📄 base.py # Base models
│ │ │ └── 📄 init_db.py # Database initialization
│ │ │
│ │ ├── 📁 models/ # SQLAlchemy models
│ │ │ ├── 📄 __init__.py
│ │ │ ├── 📄 ephemeris.py # Astronomical data models
│ │ │ ├── 📄 prophecy.py # Theological models
│ │ │ ├── 📄 alert.py # Alert models
│ │ │ └── 📄 event.py # Event models
│ │ │
│ │ ├── 📁 schemas/ # Pydantic schemas (DTOs)
│ │ │ ├── 📄 __init__.py
│ │ │ ├── 📄 ephemeris.py
│ │ │ ├── 📄 prophecy.py
│ │ │ └── 📄 alert.py
│ │ │
│ │ └── 📁 services/ # Business logic
│ │ ├── 📄 __init__.py
│ │ ├── 📁 ingestion/ # Data ingestion services
│ │ │ ├── 📄 horizons_client.py # JPL Horizons via Astroquery
│ │ │ ├── 📄 sentry_client.py # JPL Sentry
│ │ │ ├── 📄 usgs_client.py # USGS Earthquakes
│ │ │ └── 📄 noaa_client.py # NOAA Space Weather
│ │ ├── 📁 analysis/ # Analytical engines
│ │ │ ├── 📄 pds_engine.py # Prophetic Data Signatures
│ │ │ ├── 📄 rev12_calculator.py # Revelation 12 alignment
│ │ │ └── 📄 correlator.py # Astro-geophysical correlations
│ │ └── 📁 czml/ # CZML generation
│ │ └── 📄 generator.py
│ │
│ └── 📁 tests/ # Pytest test suite
│ ├── 📄 conftest.py
│ ├── 📁 test_api/
│ ├── 📁 test_services/
│ └── 📁 test_models/
│
├── 📁 docs/ # Documentation
│ ├── 📄 API_REFERENCE.md # API documentation
│ ├── 📄 DATABASE_SCHEMA.md # Database design
│ ├── 📄 DEPLOYMENT.md # Deployment guide
│ └── 📁 diagrams/ # Architecture diagrams
│
├── 📁 docker/ # Docker configurations
│ ├── 📄 Dockerfile.frontend
│ ├── 📄 Dockerfile.backend
│ └── 📄 nginx.conf # Reverse proxy config
│
└── 📁 .github/ # GitHub specific
├── 📁 workflows/
│ ├── 📄 ci.yml # Continuous Integration
│ └── 📄 deploy.yml # Deployment workflow
└── 📄 PULL_REQUEST_TEMPLATE.md
Goal: Get your development environment fully operational in 2 hours.
Create the project constitution that will guide all AI interactions:
cd celestial-signs
specify initThe specify/constitution.md file will be auto-generated. Edit it:
# Celestial Signs - Project Constitution
## Core Mission
Build a web application that monitors astronomical events and correlates them with biblical eschatological prophecies, providing a visual experience similar to theskylive.com but with unique prophetic analysis capabilities.
## Technical Stack
### Frontend
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript (strict mode)
- **UI Library**: Catalyst UI (commercial subscription)
- **Styling**: Tailwind CSS
- **3D/Visualization**:
- Three.js + @react-three/fiber (solar system)
- Cesium.js (Earth-centric geospatial)
- D3-Celestial.js (2D star maps)
### Backend
- **Framework**: FastAPI (Python 3.11+)
- **Database**: PostgreSQL 15 + PostGIS extension
- **ORM**: SQLAlchemy 2.0
- **Data Sources**:
- Astroquery (JPL Horizons interface)
- Skyfield (astronomical calculations)
- czml3 (Cesium data format)
### Development Workflow
- **IDE**: VSCode with GitHub Copilot (Claude Sonnet 4.5 agent)
- **Methodology**: Spec-Driven Development (SDD) via spec-kit
- **Version Control**: Git with feature branch workflow
- **Testing**: Pytest (backend), Vitest (frontend)
## Architectural Principles
### 1. Separation of Concerns
- Frontend: Visualization and user interaction ONLY
- Backend: All business logic, data processing, and analysis
- Database: Single source of truth for all data
### 2. API-First Design
- RESTful API with OpenAPI documentation
- JSON responses for all endpoints
- CZML format for Cesium.js time-dynamic data
### 3. Data Accuracy Priority
- JPL Horizons is the authoritative source for ephemerides
- Always use Astroquery for Horizons interaction (handles parsing)
- Validate all external API responses before database insertion
- Log all data ingestion errors centrally
### 4. Theological Framework
- Prophetic Data Signatures (PDS) based on literal, premillennial interpretation
- Scripture as the foundational text (implemented in Theological Data Layer)
- Non-astrological: Focus on astronomy and biblical prophecy, not horoscopes
## Code Standards
### Python (Backend)
```python
# REQUIRED: Type hints for all functions
def fetch_ephemeris(object_name: str, start_time: str) -> list[EphemerisData]:
"""
Fetch ephemeris data from JPL Horizons using Astroquery.
Args:
object_name: Target object (e.g., "Mars", "3I/ATLAS")
start_time: ISO 8601 start time
Returns:
List of ephemeris data points
Raises:
HorizonsAPIError: If API request fails
"""
pass
# Use PEP 8 formatting (enforced by Black)
# Use descriptive variable names
# Add docstrings to all public functions
# Handle errors explicitly (no bare except clauses)// REQUIRED: Interface definitions for all props
interface SolarSystemViewerProps {
initialDate: Date;
targetObject?: string;
onObjectSelect?: (objectId: string) => void;
}
// Use functional components with hooks
// Prefer composition over inheritance
// Use Catalyst UI components for all standard UI elements
// Follow Prettier formatting (auto-format on save)
// TODO: Copilot will generate component implementation following these patterns// ALWAYS use Catalyst components when available:
// - Button, Input, Select, Checkbox, Radio
// - Dialog, Dropdown, Popover
// - Table, Badge, Avatar
// - NavbarRoot, Sidebar, Divider
// Example - Navbar implementation:
import { Navbar, NavbarSection, NavbarItem } from '@catalyst/navbar'
// TODO: Copilot will generate Navbar with proper Catalyst patterns- Minimum 80% code coverage for backend services
- Integration tests for all API endpoints
- Visual regression tests for key UI components (Playwright)
- Load testing for data ingestion services
- No user authentication required (personal use)
- API rate limiting to prevent abuse
- Input validation on all API endpoints
- SQL injection protection (use parameterized queries)
- Initial page load: < 3 seconds
- API response time: < 500ms (95th percentile)
- 3D visualization: 60 FPS on modern hardware
- Database queries: < 100ms for cached data
# Backend: Structured error responses
{
"error": {
"code": "HORIZONS_API_ERROR",
"message": "Failed to fetch ephemeris data",
"details": "Connection timeout after 30s",
"timestamp": "2025-10-24T19:30:00Z"
}
}- Containerized with Docker
- Free tier cloud services (Vercel, Railway, or Fly.io)
- PostgreSQL: Supabase free tier or Docker local
- Static assets: CDN (Cloudflare or similar)
- Provide complete context about the feature
- Reference this constitution
- Include user stories or use cases
- Specify exact data sources if relevant
- Ask for modular, testable design
- Request detailed function signatures
- Specify error handling requirements
- Ask for database schema changes if needed
- One task at a time for complex features
- Request unit tests with implementation
- Ask for comments that explain "why", not just "what"
- Verify against constitution principles
- Reusable components in
components/ui/ - Shared utilities in
lib/ - Backend services follow single responsibility
- Database models centralized in
models/
- README for each major module
- Inline comments for complex logic
- OpenAPI spec for all endpoints
- Database schema documentation
This constitution is the single source of truth for AI-assisted development. All code generation should align with these principles.
#### Step 1.2: VSCode Configuration (20 minutes)
Create `.vscode/settings.json`:
```json
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"[python]": {
"editor.defaultFormatter": "ms-python.black-formatter",
"editor.formatOnSave": true
},
"python.linting.enabled": true,
"python.linting.pylintEnabled": false,
"python.linting.flake8Enabled": true,
"python.testing.pytestEnabled": true,
"typescript.preferences.importModuleSpecifier": "relative",
"github.copilot.enable": {
"*": true,
"yaml": true,
"plaintext": true,
"markdown": true
},
"github.copilot.advanced": {
"inlineSuggestCount": 3
}
}
Create .vscode/extensions.json:
{
"recommendations": [
"github.copilot",
"github.copilot-chat",
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-python.python",
"ms-python.black-formatter",
"bradlc.vscode-tailwindcss",
"prisma.prisma"
]
}- Open VSCode Command Palette (
Cmd+Shift+PorCtrl+Shift+P) - Type: "Preferences: Open User Settings (JSON)"
- Add or verify:
{
"github.copilot.chat.model": "claude-sonnet-4.5"
}- Restart VSCode
- Open Copilot Chat and verify the model shows "Claude Sonnet 4.5"
git init
git add .
git commit -m "Initial project structure with Spec-Kit constitution"
# Create GitHub repository (replace with your username)
gh repo create celestial-signs --private --source=. --remote=origin
git push -u origin mainGoal: Get Catalyst UI working with theskylive.com-inspired layout.
cd frontend
npm install @catalyst/ui @headlessui/react @heroicons/react
npm install three @react-three/fiber @react-three/drei
npm install cesium
npm install d3-celestial d3
npm install axios swr date-fns
npm install -D @types/three @types/d3Update tailwind.config.ts:
import type { Config } from 'tailwindcss'
import catalyst from '@catalyst/tailwindcss'
const config: Config = {
content: [
'./app/**/*.{js,ts,jsx,tsx,mdx}',
'./components/**/*.{js,ts,jsx,tsx,mdx}',
'./node_modules/@catalyst/ui/**/*.{js,ts,jsx,tsx}'
],
theme: {
extend: {
colors: {
// TheSkyLive.com inspired dark theme
dark: {
bg: '#0a0e1a',
surface: '#131926',
elevated: '#1c2333',
border: '#2a3347'
},
celestial: {
sun: '#ffd700',
moon: '#e8e8e8',
planet: '#4a90e2',
comet: '#00d4ff',
alert: '#ff4757'
}
}
}
},
plugins: [catalyst]
}
export default configThis is Part 1 of the implementation package. The file is getting long. Should I continue with:
Part 2: Database Schemas & API Design Part 3: Frontend Component Templates (Copilot-optimized) Part 4: Backend Service Templates Part 5: 12-Month Roadmap with Milestones Part 6: Deployment & Cost Analysis
Let me know if you want me to continue or if you'd like me to split this into multiple files for easier reference!