📘 LifePlan – Developer Documentation Table of Contents Project Overview
Tech Stack
System Architecture & Folder Structure
Prerequisites & Local Setup
Environment Variables
Frontend Architecture (React/Redux)
Backend Architecture (Node/Express)
OpenAI Assistants Integration
Available Scripts
- Project Overview LifePlan is a comprehensive, faith-based web application designed to help users thoughtfully map out their life goals and assess their current state across five core domains: Personal, Family & Friends, Church & Kingdom, Vocation, and Community.
By integrating structured assessment frameworks with the dynamic OpenAI Assistants API, LifePlan provides users with a deeply personalized, highly interactive reflection experience. Users progress through gated modules, synthesize their thoughts with AI, and ultimately generate dynamically compiled PDF Deliverables directly from the backend.
🗺️ Core User Journey Authentication: Secure local email/password or Google OAuth registration/login.
Dashboard: Central hub tracking module completion and enforcing chronological gating.
Getting Started (Module 1): Articulating overarching goals and hopes for the LifePlan.
Where I Am Now (Module 2): A 4-column contextual assessment (Right, Wrong, Confused, Missing) across the 5 domains, enhanced by AI contextual follow-ups.
Perspective (Module 3): Deeper analysis unlocking actionable insights.
Deliverables: Final compiled PDFs of the user's LifePlan journey, generated natively on the server.
- Tech Stack This project utilizes a highly modern, bleeding-edge MERN stack.
Frontend (Client) Framework: React.js (v19) built with Vite (v7).
Language: TypeScript (v5.9).
Styling: Tailwind CSS (v4) & custom CSS Modules.
State Management: Redux Toolkit (@reduxjs/toolkit) + Redux Persist.
Routing: React Router DOM (v7).
Icons & UI: Lucide React, React Toastify.
Auth Integration: @react-oauth/google.
Backend (Server) Runtime / Framework: Node.js, Express.js (v5).
Execution: tsx for seamless TypeScript execution in dev.
Language: TypeScript (v6).
Database: MongoDB via Mongoose ORM (v9).
Authentication: JSON Web Tokens (JWT), bcrypt (v6) for hashing.
AI Integration: OpenAI API SDK (v6) utilizing the Assistants API (Threads, Runs).
Email Service: Nodemailer (v8) via Gmail SMTP.
Document Generation: pdf-lib for robust, server-side PDF manipulation and creation.
- System Architecture & Folder Structure The project utilizes a monorepo structure, isolating the React client and Express server while keeping them in the same repository for easy deployment and typed sharing.
Plaintext LIFEPLAN/ │ ├── backend/ # Express/Node.js Server │ ├── dist/ # Compiled JavaScript output │ ├── src/ │ │ ├── config/ # DB, OpenAI, and environment setups │ │ ├── controllers/ # Route request handlers │ │ ├── middlewares/ # Auth, Module Gating, Error handling │ │ ├── models/ # Mongoose Database Schemas │ │ ├── routes/ # Express Router definitions │ │ ├── services/ # Business logic & AI Assistant logic │ │ ├── types/ # TypeScript Interfaces & Types │ │ ├── utils/ # Helper functions (PDF gen, etc.) │ │ └── index.ts # Server entry point │ ├── .env # Backend Secrets (DO NOT COMMIT) │ ├── package.json │ └── tsconfig.json │ └── frontend/ # React/Vite Client ├── public/ # Static assets ├── src/ │ ├── components/ # Reusable UI components (Modals, Gating Blocks) │ ├── config/ # Frontend configs │ ├── css/ # CSS Modules (*.module.css) │ ├── hooks/ # Custom React hooks (useAIQuestions, useModuleAccess) │ ├── store/ # Redux store & slices (authSlice) │ ├── types/ # TypeScript definitions │ ├── utils/ # Helpers (synthesisUtils, moduleHelpers) │ └── main.tsx # React application mount point ├── .env.local # Frontend variables (DO NOT COMMIT) ├── eslint.config.js ├── index.html └── package.json 4. Prerequisites & Local Setup Prerequisites Node.js (v18+ recommended, compatible with v20+)
MongoDB (Local instance running on mongodb://localhost:27017 or MongoDB Atlas URI)
Installation
- Clone the repository and install dependencies:
Bash
cd backend npm install
cd ../frontend npm install 2. Setup Environment Variables: Follow the instructions in Section 5 to create your .env files.
- Start the Development Servers: Open two separate terminal windows.
Terminal 1 (Backend):
Bash cd backend npm run dev
Server runs on http://localhost:4000
Terminal 2 (Frontend):
Bash cd frontend npm run dev
Client runs on http://localhost:5173
- Environment Variables Create two separate environment files to run the application locally. Never commit these files to version control.
Backend: backend/.env Create this file in the backend/ directory.
Code snippet
PORT=4000 FRONTEND_URL=http://localhost:5173
MONGO_URI=mongodb://localhost:27017/lifeplan
SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_SECURE=false SMTP_USER=your_email@gmail.com SMTP_PASS=your_app_specific_password MAIL_FROM="LifePlan your_email@gmail.com" ADMIN_EMAIL=admin@example.com
JWT_SECRET=your_secure_jwt_secret_key JWT_EXPIRES_IN=7d
GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com GOOGLE_CLIENT_SECRET=your_google_client_secret
OPENAI_API_KEY=sk-your_openai_api_key
ASSISTANT_ID_GETTING_STARTED=asst_xxxxxxxxxxxxxxxx ASSISTANT_ID_DOMAIN_FOLLOWUP=asst_xxxxxxxxxxxxxxxx ASSISTANT_ID_WHERE_I_AM=asst_xxxxxxxxxxxxxxxx ASSISTANT_ID_CONTEXTUAL_FOLLOWUP=asst_xxxxxxxxxxxxxxxx Frontend: frontend/.env.local Create this file in the frontend/ directory.
Code snippet VITE_API_URL=http://localhost:4000/api/ VITE_GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com 6. Frontend Architecture (React/Redux) Global State (Redux Toolkit) The frontend uses Redux Toolkit paired with redux-persist to maintain session state across browser reloads (stored in localStorage).
authSlice: Manages the user's authentication status.
state.auth.token: Holds the active JWT.
state.auth.userdata: Holds the user profile payload (name, email, etc.).
Main Routing (react-router-dom) / — Landing Page & Auth forms (Login/Register).
/dashboard — Main Hub. Tracks module completion percentages and handles lock/unlock (gating) logic.
/getting-started — Module 1: Establishes overarching goals.
/where-i-am-now — Module 2: The 4-column assessment matrix (Right, Wrong, Confused, Missing).
/perspective — Module 3: Deep dive into life perspectives.
/journey-complete — Final Deliverables screen to download PDFs.
Caching AI Responses To prevent spamming the OpenAI API on page reloads, the custom hooks inside src/hooks/useAIQuestions.ts cache the AI responses in localStorage for 24 hours.
Dev Tip: To bypass the cache and force a fresh AI generation while testing, append ?no-cache to the URL (e.g., http://localhost:5173/where-i-am-now?no-cache).
- Backend Architecture (Node/Express) All protected API routes expect a valid JWT in the headers: Authorization: Bearer .
Auth & User (/api/auth) POST /register, POST /login — Standard email/password flow.
POST /google-login — Authenticate via Google OAuth token.
POST /verify-otp & /resend-otp — Email verification logic.
POST /forgot-password & /reset-password — Account recovery.
GET /me — Validate token and return current user profile.
Module Progression & Data Access Control: GET /api/access-check/:module — Middleware verifies prerequisite module completion.
Getting Started: GET|PUT|DELETE /api/modules/getting-started-modules
Where I Am Now: GET|PUT|DELETE /api/modules/where-i-am-now
Perspective: GET|PUT|DELETE /api/perspective/module-3
Backend PDF Generation (pdf-lib) LifePlan generates crisp, professional PDFs directly on the server using pdf-lib. The server extracts the user's saved JSON progress from MongoDB, writes it onto a formatted PDF template/buffer, and streams it to the client.
GET /api/modules/getting-started-modules/pdf
GET /api/modules/where-i-am-now/pdf
GET /api/modules/life-plan-modules/pdf/:document
- OpenAI Assistants Integration (CRITICAL) How It Works Instead of using standard chat.completions (which are stateless), LifePlan utilizes the OpenAI Assistants API (v4 SDK).
The backend creates a Thread for the user.
It adds the user's reflection as a Message.
It creates a Run (openai.beta.threads.runs.createAndPoll()) and waits for the Assistant to finish thinking.
This ensures the AI has stateful memory of previous follow-ups within a session.
Setting up the Assistants For a new developer setting up a new environment, you must create 4 custom Assistants in the OpenAI Dashboard to populate your .env file.
Go to platform.openai.com/assistants.
Click + Create Assistant.
Create the following four assistants, assigning them the gpt-4-turbo or gpt-4o model.
Crucial: For the first three, you must set the "Response Format" in the dashboard to JSON Object.
Assistant 1: Getting Started
ID Mapping: ASSISTANT_ID_GETTING_STARTED
Response Format: JSON Object
Instructions: Provide the system prompt to generate the 4-option orientation JSON.
Assistant 2: Domain Followup
ID Mapping: ASSISTANT_ID_DOMAIN_FOLLOWUP
Response Format: JSON Object
Instructions: Provide the system prompt to generate 2-3 specific follow-up questions in JSON format.
Assistant 3: Where I Am Now
ID Mapping: ASSISTANT_ID_WHERE_I_AM
Response Format: JSON Object
Instructions: Provide the system prompt to generate the deterministic 4-column (right/wrong/confused/missing) JSON object.
Assistant 4: Contextual Followup
ID Mapping: ASSISTANT_ID_CONTEXTUAL_FOLLOWUP
Response Format: Text (Standard)
Instructions: Provide the system prompt to output a warm, reflective 80-word conversational response with the user's name in the middle or end.
- Available Scripts Backend (/backend) npm run dev: Starts the development server using tsx watch.
npm run build: Compiles TypeScript to JavaScript in the /dist directory.
npm start: Runs the compiled output (node dist/index.js).
Frontend (/frontend) npm run dev: Starts the Vite development server with Hot Module Replacement.
npm run build: Type-checks and builds the React app for production into /dist.
npm run preview: Previews the production build locally.
npm run lint: Runs ESLint for code quality checks.