Meditate

Meditate is a full-stack daily spiritual reflection app.

It helps a signed-in user:

• follow a Bible plan
• read today's scripture
• select verses for reflection
• generate AI-assisted summary, prayer ideas, and action steps
• persist and reload AI output for today's meditation

Tech Stack

• Backend: ASP.NET Core Web API, EF Core, SQL Server, JWT auth
• Frontend: React + TypeScript + Vite + Tailwind
• AI: OpenAI API (configured via environment variable or configuration)

Repository Layout

backend/   ASP.NET Core API
frontend/  React + TypeScript client

Architecture Overview

High-level flow for daily usage:

flowchart LR
  UI[React UI] --> Hook[useDashboardData hook]
  Hook --> API[Axios API client]
  API --> Controllers[ASP.NET Controllers]
  Controllers --> Services[Application Services]
  Services --> DB[(SQL Server via EF Core)]
  Services --> OpenAI[OpenAI API]
  DB --> Services
  OpenAI --> Services

Loading

Key frontend separation:

• Components render UI cards and pages.
• Hooks manage async logic and local feature state.
• Context provides global auth state.

Key backend separation:

• Controllers handle HTTP contracts.
• Services hold business logic.
• AppDbContext defines relationships/indexes and persistence.

Quick Start

1. Prerequisites

• .NET SDK 10.x
• Node.js 20+
• SQL Server (local or container)

2. Configure Backend

1. Copy backend/appsettings.example.json to backend/appsettings.Development.json.
2. Set a strong JWT key and local DB connection string.
3. Set OpenAI key (recommended via env var):

export OPENAI_API_KEY="your_key_here"

Optional: run SQL Server using Docker (if you do not have a local SQL instance):

docker run --name meditate-sql \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=YourNewPassword10" \
  -p 1433:1433 \
  -d mcr.microsoft.com/mssql/server:2022-latest

Then use a connection string similar to:

Server=localhost,1433;Database=MeditateDb;User Id=sa;Password=YourNewPassword10;TrustServerCertificate=True

3. Run Backend

cd backend
dotnet ef database update
dotnet run

API default URL:

• http://localhost:5172

4. Configure Frontend

1. Copy frontend/.env.example to frontend/.env.local.
2. Confirm VITE_API_BASE_URL points to the backend.

5. Run Frontend

cd frontend
npm install
npm run dev

Frontend default URL:

• http://localhost:5173

Build Commands

Backend:

cd backend
dotnet build

Frontend:

cd frontend
npm run build

Security and Secrets

Never commit:

• API keys
• JWT secrets
• production DB passwords
• .env files with real credentials
• appsettings.Development.json with sensitive values

Use instead:

• environment variables
• .NET user secrets
• local-only files already ignored by Git

OpenAI resolution order in backend:

1. OPENAI_API_KEY environment variable
2. OpenAI:ApiKey in app configuration

GitHub Safety Checklist

Before publishing or opening a PR:

1. Confirm no secrets are staged:

git status
git diff --staged

1. If a secret was accidentally committed, rotate it immediately and remove it from history.

2. Ensure CI passes locally:

cd backend && dotnet build
cd ../frontend && npm run build

1. Keep dependencies updated and review alerts from Dependabot and GitHub Security tab.

API Notes

• Authentication uses Bearer JWT tokens.
• AI generation endpoint remains:
  • POST /api/ai/generate-day
• Today meditation endpoint returns saved AI data:
  • GET /api/meditation/today

Troubleshooting

• If you see BadImageFormatException during active development:

  1. stop watch processes
  2. run dotnet clean && dotnet build
  3. start backend again

• If backend cannot connect to SQL Server on localhost,1433:

  1. verify Docker Desktop is running
  2. verify container is up: docker ps
  3. confirm password and connection string match
  4. run dotnet ef database update again

• If frontend HMR shows old parse errors after a fix:

  1. stop dev server
  2. run npm run build to confirm syntax
  3. restart npm run dev