WordFury

An AI-powered document assistant and multi-platform reference app:

• Node.js + Express REST APIs for chat, document processing, payments, etc.
• Python microservice for embeddings, vector indexing and retrieval
• Flutter client targeting Web, iOS, Android, macOS and Windows

Features

• Document parsing and Retrieval-Augmented QA (PDF and webpages)
• Chat with models (GPT-3.5/4 family), DALL·E 3 image generation, Vision prompts
• Accounts, rate limiting, token usage-based accounting (reference)
• Stripe/Alipay payment samples (opt-in)
• Flutter multi-platform client with local cache and i18n

Architecture Overview

High-level Architecture

• Node.js (Express): REST API server coordinating LLM functionality, storage, and payments
• Python Flask: Embedding/indexing service providing streaming answers for document Q&A
• MongoDB: Stores user data, notes, files, and order information
• Flutter: Cross-platform client consuming API services

Core Technical Modules

1. Document Processing & RAG System

• Tech Stack: Python Flask + LangChain/OpenAI + Chroma/FAISS vector databases
• Functionality: PDF/webpage parsing → text chunking → vectorization → similarity retrieval → context-augmented generation
• Key Files: chatpdf.py, q_a_embeddings.py
• Process Flow: file upload → text extraction → embedding generation → vector storage → semantic retrieval

2. AI Chat Engine

• Tech Stack: Node.js + OpenAI SDK + session management
• Model Support: GPT-3.5/4, DALL-E 3, Vision models
• Features: Multi-turn dialogue, context memory, image generation, visual understanding
• Key Files: routes/ai.js, routes/gpt.js

3. User Management & Auth

• Tech Stack: Passport.js + JWT + session management
• Functionality: Registration/login, OAuth integration, permission control, user profiles
• Data Model: MongoDB user collections + session storage
• Key Files: routes/users.js, utils.js

4. Payment System

• Tech Stack: Stripe SDK + webhook handling + order management
• Functionality: Payment link generation, payment status tracking, subscription management, refund processing
• Key Files: routes/stripe.js, test/stripe.test.js

5. Cross-platform Client

• Tech Stack: Flutter + GetX state management + local caching
• Platform Support: iOS, Android, Web, macOS, Windows, Linux
• Features: Responsive UI, offline caching, internationalization, theme switching
• Key Directory: wordfury/lib/

6. Chrome Extension

• Tech Stack: Chrome Extension Manifest V3 + content scripts
• Functionality: Quick webpage Q&A, text selection search, sidebar integration
• Key Directory: extension/

7. Data Persistence

• Database: MongoDB (document storage)
• Caching: Redis (session/cache)
• File Storage: Local filesystem + CDN
• Data Models: users, files, conversation history, payment orders

8. API Design

• Architecture: RESTful API + WebSocket (real-time communication)
• Authentication: JWT Token + Session Cookie
• Rate Limiting: API rate limiting based on user tiers
• Documentation: Auto-generated API documentation

Performance & Scalability

• Load Balancing: Nginx reverse proxy
• Caching Strategy: Multi-level caching (browser, CDN, application layer)
• Database Optimization: Index optimization, pagination queries, aggregation pipelines
• Scalability: Microservices architecture supporting horizontal scaling

Directory Structure

WordFury/
├── app.js                 # Express main application entry
├── app.py                 # Python Flask service entry
├── main.py               # Python main service file
├── bin/                  # Startup scripts directory
│   ├── www               # Node.js service startup script
│   └── start_python_server # Python service startup script
├── routes/               # Express route definitions
│   ├── ai.js             # AI-related routes (file processing, chat, etc.)
│   ├── users.js          # User management routes
│   ├── stripe.js         # Payment-related routes
│   ├── admin.js          # Admin routes
│   ├── gpt.js            # GPT model-related routes
│   └── index.js          # Root routes
├── views/                # Server-side rendering templates (Art-template)
│   ├── index_en.art      # English homepage
│   ├── index_zh.art      # Chinese homepage
│   ├── prompts.art       # Prompts page
│   ├── register.art      # Registration page
│   ├── forgot.art        # Forgot password page
│   ├── error.art         # Error page
│   └── sitemap.art       # Sitemap
├── public/               # Static assets directory
│   ├── css/              # Stylesheets
│   ├── js/               # Frontend JavaScript
│   ├── images/           # Image assets
│   ├── cover/            # Cover image assets
│   ├── amazon.html       # Amazon demo page
│   ├── robots.txt        # SEO configuration
│   ├── sitemap.html      # Sitemap
│   └── term.html         # Terms of service
├── prompt/               # Prompt configurations
│   ├── prompt_en.json    # English prompts
│   └── prompt_zh.json    # Chinese prompts
├── wordfury/             # Flutter cross-platform client
│   ├── lib/              # Flutter main code
│   │   ├── main.dart     # Flutter application entry
│   │   ├── pages/        # Page components
│   │   ├── widgets/      # Custom widgets
│   │   ├── models/       # Data models
│   │   ├── utils/        # Utility classes
│   │   └── ...
│   ├── android/          # Android platform configuration
│   ├── ios/              # iOS platform configuration
│   ├── web/              # Web platform configuration
│   ├── macos/            # macOS platform configuration
│   ├── windows/          # Windows platform configuration
|   ├── extension/        # Chrome extension source directory
|   ├── test/             # Test files
│   └── linux/            # Linux platform configuration
├── db.js                 # MongoDB connection configuration
├── utils.js              # Common utility functions
├── chatpdf.py            # PDF chat processing script
├── q_a_embeddings.py     # Q&A embedding processing
├── json_to_db.py         # JSON data import to database
├── requirements.txt      # Python dependencies
├── package.json          # Node.js dependencies and scripts
├── prompt.json           # Prompt configuration
└── .env.example          # Environment variables example

Requirements

• Node.js >= 18
• Python >= 3.9
• MongoDB (local or hosted)
• Flutter toolchain (if you want to run the client)

Quickstart

# Clone
git clone https://github.com/<your-account>/WordFury.git
cd WordFury

# Node dependencies
npm install

# Python dependencies
pip install -r requirements.txt

# Copy env file and fill it
cp .env.example .env.local
# On Windows PowerShell
# Copy-Item .env.example .env.local

Environment

Fill .env.local with your secrets. See .env.example for a complete reference.

Key variables:

• General: NODE_ENV, SESSION_SECRET, PY_SERVER_SECRET
• Database: MONGODB_URL
• OpenAI: OPENAI_API_KEY, OPENAI_ORG_ID
• Baidu (optional): BAIDU_APP_ID, BAIDU_API_KEY, BAIDU_SECRET_KEY
• SendGrid (optional): SENDGRID_API_KEY, MAIL_FROM_EMAIL, MAIL_FROM_NAME
• Stripe (optional): STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_ID (+ test variants)
• Apple Sign In (optional): APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_BUNDLE_ID_IOS, APPLE_SERVICE_ID_WEB, APPLE_REDIRECT_URI, APPLE_AUTHKEY_PATH
• Internal (optional): INTERNAL_TOKEN

Run

• Start Node API (port configured by bin/www):

npm run start
# Dev (Windows):
npm run start-dev-w
# Dev (Unix):
npm run start-dev

• Start Python service (default 9997):

npm run start-python
# Dev
npm run start-python-dev

Key Endpoints (Node)

• POST /ai/process_file: upload file and create vector index
• POST /ai/chat: chat with context
• POST /ai/get_files: list user files
• GET /stripe/payurl/:userid: create payment link (Stripe)
• POST /stripe/webhook: Stripe webhook

Development

• Use .env.local for secrets (ignored by git)
• A dev proxy (HttpsProxyAgent) is supported if required by your network
• MongoDB URL is read from env; avoid hardcoding credentials
• Enable Stripe/Apple/SendGrid only after setting respective env and console configs

Testing

npm test
# or
npm run test:watch

Deployment

• Prepare environment variables (use a secret manager in production)
• Node service:
  • Any Node 18+ host (PM2, Docker, or serverless)
  • Example PM2:

    pm2 start bin/www --name wordfury
    pm2 save

  • Example Dockerfile (simplified):

    FROM node:18-alpine
    WORKDIR /app
    COPY package*.json ./
    RUN npm ci --only=production
    COPY . .
    EXPOSE 3000
    CMD ["node", "bin/www"]

• Python service:
  • Run with gevent/WSGI behind Nginx/Caddy on port 9997
• Webhook and callbacks:
  • Stripe webhook -> /stripe/webhook
  • Apple/Alipay redirects -> configure your public URLs in platform consoles
• Production hardening:
  • HTTPS termination at reverse proxy
  • Strict CORS policy
  • Strong random SESSION_SECRET/PY_SERVER_SECRET
  • Observability (logs/metrics), backups for MongoDB

Contributing

We welcome contributions of all kinds. To contribute:

1. Fork the repo and create your feature branch from main
2. Keep changes focused and small; follow existing code style
3. Add tests and update docs if needed
4. Ensure npm test passes locally
5. Open a pull request with a clear title and description

Code style guidelines:

• Use clear, descriptive names
• Prefer early returns and explicit error handling
• Keep functions small and cohesive
• Avoid committing secrets or local assets

License

This project is licensed under the MIT License. See LICENSE for details.