AI-assisted, multi-step onboarding flow for the fictional acCOUNT ME IN investment platform. The app showcases secure identity capture, Gemini-powered assistance, and polished UX patterns ready to integrate with a real brokerage backend.
- Live Preview
- Features
- Architecture Overview
- Prerequisites
- Environment Configuration
- Getting Started
- Available Scripts
- Application Flow
- Security & Data Handling
- Troubleshooting
- Guided onboarding wizard with nine progressive disclosure steps, animated progress bar, and contextual help for every stage.
- Identity & Security capture featuring masked SSN entry, client-side hashing, and validation to keep sensitive data safe.
- Document scanner modal (
components/DocumentScanner.tsx) that uploads an ID image, invokes Geminigemini-2.5-flash, and auto-fills profile fields while filtering placeholder text. - Embedded chat assistant (
components/ChatAssistant.tsx) providing empathetic, compliance-aware support using Geminigemini-2.0-flash-001. - Investment profile generation (
ConfirmationStep) that summarizes the user and suggests diversified categories via Gemini content generation. - Accessibility-first UI with keyboard-friendly controls, high-contrast design tokens, and descriptive helper text.
- TypeScript domain models (
types.ts) for consistent state management across steps.
HackNC/
├─ App.tsx # Root shell, orchestrates step navigation & shared state
├─ components/
│ ├─ steps/ # Individual step screens (Welcome → Confirmation)
│ ├─ ChatAssistant.tsx # Floating AI helper
│ ├─ DocumentScanner.tsx # Gemini-powered ID ingestion modal
│ └─ ProgressBar.tsx # Step tracker UI
├─ services/
│ ├─ geminiService.ts # Gemini client helpers (chat + investment profile)
│ └─ encryption.ts # Client-side SSN hashing utilities
├─ constants.ts # Step metadata & phone region definitions
└─ types.ts # Application-wide TypeScript interfaces
React 19 + Vite 6 power the build pipeline, while the UI relies on Tailwind-like utility classes for styling (prebaked into the component markup).
- Node.js 18.18+ (or any version compatible with Vite 6)
- npm 9+ (ships with modern Node distributions)
- A Google Gemini API key with access to the
gemini-2.0-flash-001andgemini-2.5-flashmodels
Create a .env file in the project root with one of the following:
# Preferred (keeps model helpers consistent)
VITE_GEMINI_API_KEY=your_google_gemini_key
# Backwards-compatible fallback used in the current code
VITE_API_KEY=your_google_gemini_keyOnly one variable is required—services/geminiService.ts checks VITE_GEMINI_API_KEY first and falls back to VITE_API_KEY.
# Install dependencies
npm install
# Start the dev server at http://localhost:5173
npm run devThe app hot-reloads in development. To reset all wizard data, click “Start Over” from any step or refresh the browser (state is held in memory only).
npm run dev– Launch Vite in development mode.npm run build– Generate a production build indist/.npm run preview– Serve the production build locally for verification.
The wizard walks applicants through the following steps (constants.ts):
- Welcome – Hero animation, account type selection, custom exit transitions.
- Profile Basics – Legal name, contact info, military experience with conditional fields.
- Identity & Security – DOB, citizenship, protected SSN entry, Gemini-powered document scan.
- Address – Primary residence capture with AI-assisted tips.
- Employment – Employment status, FINRA affiliations, control-person logic.
- Financial Profile – Risk/goal/income/experience inputs for downstream personalization.
- Trusted Contact – Optional guardian contact capture with skip support.
- Review & Submit – Summary page with masked SSN and edit hints.
- Confirmation – Gemini-generated investment personality and category suggestions.
Progress is stored in a single UserData object within App.tsx, shared with child components via props and partial updates.
- SSNs never render in plain text.
SecurityStepmasks input visually and hashes values with SHA-256 (falling back to Base64 if needed) usingservices/encryption.ts. - Uploaded IDs are processed client-side; the sample implementation sends base64 data to Gemini for extraction, then immediately clears the modal.
sanitizeExtractedData(inSecurityStep) strips placeholder values such as “YOUR CITY” or “TEST” before updating state, ensuring the Address step starts blank when scan results are unreliable.- No data persists between sessions; local state resets on refresh. Integrate your own API layer for persistence or submission.
- Blank AI responses – Confirm the Gemini key is valid and has access to the required models.
- Document scan stuck – Large images (>5 MB) or non-image files are rejected; check console logs for validation errors.
- Build failures on older Node versions – Upgrade to Node 18+ for native ESM + Vite compatibility.
The repository also includes the stock React + Vite starter located in my-react-app/. It mirrors Vite’s default scaffold and may be useful for rapid prototyping or comparing configurations. Highlights from the template:
- Ships with @vitejs/plugin-react (Babel) and can be swapped for the
react-swcvariant if desired. - Hot Module Replacement (HMR) is enabled out of the box.
- ESLint is preconfigured; for production apps you can expand it with type-aware rules via
typescript-eslint. - React Compiler is disabled by default to preserve local dev performance—see the React docs if you want to enable it.
If you work inside my-react-app/, follow the same setup instructions as above, or run npm create vite@latest for a fresh scaffold.
Uses codex to help with the structure of the code, implemented Gemini flash 2.5 API to help the app easier to set up, more encouraging and friendly to beginners.
Need help extending the experience (e.g., wiring to back-end services or adding analytics)? Open an issue or reach out to the project maintainers. Happy hacking!