Environment Setup¶

External dependencies, environment variables, and setup for MagicON AI.

Required External Services¶

1. Nexar API (Component Search)¶

Purpose: Real-time component search, availability, pricing

Setup:

# Get credentials from https://nexar.com/api
# Add to config/.env or .env
NEXAR_CLIENT_ID=your_client_id
NEXAR_CLIENT_SECRET=your_client_secret

Fallback: Validated database (backend/categorized_databases/) is used if Nexar fails

2. Google Gemini API (AI Chat)¶

Purpose: AI-driven design assistance and chat

Setup:

# Get API key from https://ai.google.dev/
# Add to config/.env
GOOGLE_GEMINI_API_KEY=your_api_key
# or GEMINI_API_KEY=your_api_key

Optional: Can use Ollama instead for local LLM

Live pricing (when Nexar not used): If Nexar is not configured, the app can use Gemini with Google Search grounding for component price/availability; set GEMINI_API_KEY or GOOGLE_GEMINI_API_KEY. Results are cached 7 days.

3. Supabase (Authentication & Cloud Storage)¶

Purpose: User authentication, JWT verification, project storage

Setup:

# Create project at https://supabase.com
# Add to config/.env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_JWT_SECRET=your_jwt_secret
SUPABASE_SERVICE_KEY=your_service_key
SUPABASE_ANON_KEY=your_anon_key
SUPABASE_WEBHOOK_SECRET=your_webhook_secret

Authentication Flow: - Freemium access (no sign-in required for exploration) - Sign-in only required for CAD file downloads - JWT with ES256 and HS256 support

4. Ollama (Local LLM - Optional)¶

Purpose: Local AI chat without external API

Setup:

# Install Ollama from https://ollama.ai
# Pull model
ollama pull llama3

# Add to config/.env
OLLAMA_URL=http://localhost:11434
DEFAULT_MODEL=llama3

Models: llama3 (recommended), mistral:latest, or any Ollama-compatible model

5. KiCad 10.0 (Required for Export)¶

Purpose: KiCad Python API for schematic/PCB generation

Installation: - Download from https://www.kicad.org/download/ - Install to C:\Program Files\KiCad\10.0\ (Windows) - Verify Python path: C:\Program Files\KiCad\10.0\bin\python.exe

Verification:

"C:\Program Files\KiCad\10.0\bin\python.exe" -c "import pcbnew; print('KiCad Python OK')"

Environment Variables Reference¶

Frontend (.env)¶

VITE_FASTAPI_URL=http://localhost:8000
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key
VITE_FORCE_HTTPS=false  # true in production

Backend (config/.env or .env)¶

# Server
PORT=8000  # FastAPI backend port (read by backend/main.py, defaults to 8000)
ENVIRONMENT=development  # or production

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_JWT_SECRET=your_jwt_secret
SUPABASE_SERVICE_KEY=your_service_key
SUPABASE_ANON_KEY=your_anon_key
SUPABASE_WEBHOOK_SECRET=your_webhook_secret

# Nexar API
NEXAR_CLIENT_ID=your_client_id
NEXAR_CLIENT_SECRET=your_client_secret

# Google Gemini
GOOGLE_GEMINI_API_KEY=your_api_key

# Security
FORCE_HTTPS=false  # true in production
TRUSTED_HOSTS=localhost,127.0.0.1
CORS_ORIGINS=http://localhost:5180  # comma-separated; read by backend/app_config.py

# Knowledge Base (RAG)
KNOWLEDGE_BASE_PATH=./knowledge
EMBEDDING_MODEL=all-MiniLM-L6-v2
VECTOR_DIMENSION=384

# Logging
LOG_LEVEL=info  # debug, info, warning, error
DEBUG=false

# Email transport (lifecycle + retention emails)
EMAIL_NOTIFICATIONS_ENABLED=false   # master switch; no email is sent unless true
EMAIL_SERVICE=mailersend            # smtp | sendgrid | mailersend
EMAIL_FROM=noreply@your-domain.com
SMTP_PASSWORD=your_api_key          # SendGrid/MailerSend API key goes HERE (not a literal SMTP password)
APP_URL=http://localhost:5180       # base URL used to build links in emails

# Retention loop — re-engagement email (ROI #9)
FF_REENGAGEMENT_EMAIL=false         # feature flag; default OFF — enable only after templates + address + unsubscribe are reviewed
REENGAGEMENT_JOB_SECRET=            # shared secret for the daily cron: sent as the X-Job-Secret header to POST /api/jobs/reengagement
EMAIL_UNSUB_SECRET=                 # HMAC signing key for one-click unsubscribe links (keep stable; rotating it invalidates live links)
COMPANY_POSTAL_ADDRESS=            # CAN-SPAM: physical mailing address rendered in the email footer (required for a compliant bulk send)
PUBLIC_API_URL=                     # public base URL of THIS backend for unsubscribe links (defaults to APP_URL if unset)
# Targeting knobs (all optional; defaults shown)
REENGAGEMENT_IDLE_DAYS=3            # only email users whose last project activity is older than this
REENGAGEMENT_IDLE_MAX_DAYS=30       # ...but newer than this (skip long-cold users)
REENGAGEMENT_COOLDOWN_DAYS=14       # minimum gap between re-engagement emails to one user
REENGAGEMENT_LIFETIME_CAP=3         # never send more than this many re-engagement emails to one user
REENGAGEMENT_BATCH_LIMIT=50         # max emails per job run (bounds the blocking send loop)

Retention-loop trigger (external cron): no in-repo scheduler runs this. Point an external cron (cron-job.org / UptimeRobot) at a daily POST {PUBLIC_API_URL}/api/jobs/reengagement with header X-Job-Secret: <REENGAGEMENT_JOB_SECRET>. Use ?dry_run=true first — it returns candidate counts and sends nothing. Requires FF_REENGAGEMENT_EMAIL=true and EMAIL_NOTIFICATIONS_ENABLED=true to actually send. Prerequisite (verify once in the Supabase SQL editor): the public.projects.updated_at auto-bump trigger exists and public.users exposes email — the idle query depends on both.

Feature Flags¶

All VITE_FF_* flags live in the repo-root .env. A flag is treated as enabled when it is unset or any value other than the literal string false. Flip a flag off with =false, then force-restart Vite (e.g., touch frontend/vite.config.ts).

Flag	Default	Effect when `=false`
`VITE_FF_STANDALONE_IMPEDANCE`	`true`	Hides the "Impedance Calculator" nav entry and redirects `/app/impedance-calculator` → `/app/pcb-stackup`.
`VITE_FF_STANDALONE_LINK_BUDGET`	`true`	Hides the "Link Budget Calculator" nav entry and redirects `/app/link-budget-calculator` → `/app/rf-module`.

Optional Services (Docker Compose)¶

PostgreSQL (for future database migration)¶

db:
  image: postgres:latest
  ports:
    - "5432:5432"
  environment:
    POSTGRES_DB: pcb_stackup
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: password

Redis (for caching)¶

redis:
  image: redis:latest
  ports:
    - "6379:6379"