Skip to content

Technical_Guide-(Phase1).md

Latest commit

 

History

History
340 lines (284 loc) · 8.52 KB

Technical_Guide-(Phase1).md

File metadata and controls

340 lines (284 loc) · 8.52 KB

📘 CivicStreak — Complete Technical Implementation Guide

A Step-by-Step Engineering Documentation for Building the Full Platform

TABLE OF CONTENTS

PHASE 0: Prerequisites & Environment Setup
PHASE 1: Project Architecture & Initialization
PHASE 2: Database Design & Setup (Supabase)
PHASE 3: Backend API Development (Node.js + Express)
PHASE 4: Frontend Web App (Next.js)
PHASE 5: WhatsApp Bot Integration (Twilio)
PHASE 6: AI Integration (Google Gemini)
PHASE 7: Testing & Quality Assurance
PHASE 8: Deployment & DevOps
PHASE 9: Post-Deployment & Monitoring
APPENDICES

PHASE 0: Prerequisites & Environment Setup

0.1 Required Software

Install the following on your development machine:

Software Version Download Link
Node.js v18+ LTS https://nodejs.org
npm / yarn Latest Comes with Node.js
Git Latest https://git-scm.com
VS Code Latest https://code.visualstudio.com
PostgreSQL v15+ https://postgresql.org (optional — we'll use Supabase)
Postman Latest https://postman.com

Installation Verification

# Run these commands to verify installation
node --version       # Should show v18.x.x or higher
npm --version        # Should show 9.x.x or higher
git --version        # Should show 2.x.x or higher

0.2 Required Accounts (All Free Tier)

Create accounts on these platforms:

Service Purpose URL
GitHub Code repository https://github.com
Supabase Database + Auth https://supabase.com
Vercel Frontend hosting https://vercel.com
Railway Backend hosting https://railway.app
Twilio WhatsApp Bot https://twilio.com
Cloudinary Image storage https://cloudinary.com
Google AI Studio Gemini AI API https://aistudio.google.com

0.3 Recommended VS Code Extensions

- ES7+ React/Redux/React-Native snippets
- Prettier - Code Formatter
- ESLint
- Thunder Client (API testing)
- Tailwind CSS IntelliSense
- GitLens
- Auto Rename Tag

0.4 Project Folder Structure (Final)

CivicStreak/
├── client/                    # Next.js Frontend
│   ├── public/
│   │   ├── icons/
│   │   └── images/
│   ├── src/
│   │   ├── app/               # Next.js App Router
│   │   │   ├── (auth)/
│   │   │   │   ├── login/
│   │   │   │   └── register/
│   │   │   ├── dashboard/
│   │   │   ├── portfolio/
│   │   │   ├── tasks/
│   │   │   ├── circles/
│   │   │   ├── ward/
│   │   │   ├── leaderboard/
│   │   │   ├── layout.js
│   │   │   ├── page.js
│   │   │   └── globals.css
│   │   ├── components/
│   │   │   ├── ui/
│   │   │   ├── layout/
│   │   │   ├── dashboard/
│   │   │   ├── tasks/
│   │   │   ├── portfolio/
│   │   │   ├── circles/
│   │   │   └── ward/
│   │   ├── lib/
│   │   │   ├── supabase.js
│   │   │   ├── api.js
│   │   │   └── utils.js
│   │   ├── hooks/
│   │   ├── context/
│   │   └── constants/
│   ├── tailwind.config.js
│   ├── next.config.js
│   └── package.json
│
├── server/                    # Node.js + Express Backend
│   ├── src/
│   │   ├── config/
│   │   │   ├── database.js
│   │   │   ├── cloudinary.js
│   │   │   └── twilio.js
│   │   ├── controllers/
│   │   │   ├── authController.js
│   │   │   ├── taskController.js
│   │   │   ├── userController.js
│   │   │   ├── circleController.js
│   │   │   ├── portfolioController.js
│   │   │   ├── wardController.js
│   │   │   └── whatsappController.js
│   │   ├── middleware/
│   │   │   ├── auth.js
│   │   │   ├── errorHandler.js
│   │   │   └── upload.js
│   │   ├── models/
│   │   │   └── queries.js
│   │   ├── routes/
│   │   │   ├── auth.js
│   │   │   ├── tasks.js
│   │   │   ├── users.js
│   │   │   ├── circles.js
│   │   │   ├── portfolio.js
│   │   │   ├── ward.js
│   │   │   └── whatsapp.js
│   │   ├── services/
│   │   │   ├── taskAssignment.js
│   │   │   ├── streakService.js
│   │   │   ├── xpService.js
│   │   │   ├── aiService.js
│   │   │   └── whatsappService.js
│   │   └── utils/
│   │       ├── helpers.js
│   │       └── constants.js
│   ├── server.js
│   ├── .env
│   └── package.json
│
├── whatsapp-bot/              # WhatsApp Bot (can be merged with server)
│   └── (integrated in server/src/services/)
│
├── docs/                      # Documentation
│   ├── API.md
│   ├── DATABASE.md
│   └── DEPLOYMENT.md
│
├── .gitignore
├── README.md
└── docker-compose.yml         # Optional for local development

PHASE 1: Project Initialization

1.1 Create GitHub Repository

# Create a new directory
mkdir CivicStreak
cd CivicStreak

# Initialize git
git init

Create a .gitignore file in the root:

# Dependencies
node_modules/
.pnp/
.pnp.js

# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# Build output
.next/
out/
dist/
build/

# Debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

1.2 Initialize Backend (Server)

# Create server directory
mkdir server
cd server

# Initialize Node.js project
npm init -y

# Install core dependencies
npm install express cors dotenv helmet morgan
npm install @supabase/supabase-js
npm install twilio
npm install cloudinary multer multer-storage-cloudinary
npm install @google/generative-ai
npm install jsonwebtoken bcryptjs
npm install express-rate-limit
npm install node-cron

# Install dev dependencies
npm install -D nodemon

Update server/package.json scripts:

{
  "name": "CivicStreak-server",
  "version": "1.0.0",
  "description": "CivicStreak Backend API",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "seed": "node src/config/seed.js"
  },
  "keywords": ["civic", "engagement", "CivicStreak"],
  "license": "MIT"
}

1.3 Initialize Frontend (Client)

# Go back to root
cd ..

# Create Next.js app
npx create-next-app@latest client --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

cd client

# Install additional dependencies
npm install @supabase/supabase-js @supabase/auth-helpers-nextjs
npm install axios
npm install recharts                    # For charts/graphs
npm install leaflet react-leaflet      # For maps
npm install lucide-react               # For icons
npm install @radix-ui/react-dialog     # UI primitives
npm install @radix-ui/react-dropdown-menu
npm install @radix-ui/react-tabs
npm install @radix-ui/react-progress
npm install @radix-ui/react-avatar
npm install @radix-ui/react-toast
npm install class-variance-authority clsx tailwind-merge
npm install framer-motion              # Animations
npm install date-fns                   # Date utilities
npm install react-hot-toast            # Notifications
npm install react-confetti             # Celebration effects

1.4 Create Environment Files

server/.env

# Server Config
PORT=5000
NODE_ENV=development

# Supabase
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# JWT
JWT_SECRET=your_super_secret_jwt_key_CivicStreak_2024
JWT_EXPIRE=7d

# Twilio WhatsApp
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886

# Cloudinary
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Google Gemini AI
GEMINI_API_KEY=your_gemini_api_key

# Frontend URL (for CORS)
CLIENT_URL=http://localhost:3000

client/.env.local

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
NEXT_PUBLIC_API_URL=http://localhost:5000/api
NEXT_PUBLIC_APP_NAME=CivicStreak