Magic Dictionary Application

A dictionary application with a JSON database, Python CLI, and web interface with AI-powered definition generation.

Features

• JSON Database: Human-readable format with proper spacing for manual editing
• Python CLI: Search and add terms from the command line
• Web Interface: Modern dark mode UI with real-time search, A-Z filtering, and term management
• AI-Powered Definitions: Generate definitions using Perplexity AI when terms are not found
• Editable Definitions: Click any definition to edit it inline
• Quick Delete: Delete terms with a single click

Setup

Backend (Flask API)

1. Create and activate virtual environment:

cd backend
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install Python dependencies:

pip install -r requirements.txt

3. Configure Perplexity API (optional, for AI definitions):

   • Edit .env file in the project root
   • Add your Perplexity API key: PERPLEXITY_API_KEY=your_actual_api_key
   • Optionally customize the prompt template: PERPLEXITY_PROMPT_TEMPLATE=Your custom prompt with {term}
   • Set max tokens: PERPLEXITY_MAX_TOKENS=1000

4. Run the Flask server:

Option A - Using helper script (recommended):

./run.sh  # On Linux/Mac
# or
run.bat   # On Windows

Option B - Manual activation:

source venv/bin/activate  # On Windows: venv\Scripts\activate
python app.py

The API will be available at http://localhost:5002

Frontend (Web Interface)

The frontend is served directly by the Flask server. Just open http://localhost:5002 in your browser after starting the server.

Usage

CLI

Search for a term:

python cli.py hello

Add a new term (definition optional):

python cli.py --term "world" --definition "the earth"
# or, omit --definition to use the default
python cli.py --term "world"

Show help:

python cli.py

Web Interface (User)

1. Start the Flask backend server
2. Open http://localhost:5002 in your browser
3. Search for terms (minimum 3 characters)
4. Use A-Z filters to browse by first letter
5. When no results are found:
   • Click "Add" button to add the term
   • If you leave the definition empty, it will be stored as: I didn't get that
6. Click any definition to edit it inline
7. Click the × button next to any term to delete it

Admin Web Interface (with AI)

1. Start the Flask backend server
2. Open http://localhost:5002/admin in your browser
3. Behaves like the user interface, but also shows a "Define with AI" button when there are no results
4. Clicking "Define with AI" uses Perplexity to suggest a definition (requires API key in .env)
5. You can review and edit the AI-generated definition before saving

File Structure

dictionary/
├── dictionary.json          # JSON database (shared by CLI and web app)
├── dictionary.json.old      # Backup created before deletions
├── amplify.yml               # Amplify Hosting build (frontend only)
├── cli.py                    # Python CLI tool
├── .env                      # Environment variables (API keys, etc.)
├── backend/
│   ├── app.py               # Flask REST API server (local dev / CLI)
│   ├── requirements.txt     # Python dependencies
│   ├── run.sh               # Helper script to run server (Linux/Mac)
│   ├── run.bat              # Helper script to run server (Windows)
│   ├── venv/                # Python virtual environment (created on setup)
│   └── .gitignore           # Git ignore file
├── backend-ts/              # Node/TypeScript API for Amplify (Lambda + S3)
│   ├── src/                 # Express app, S3, Lambda handler
│   ├── package.json
│   └── README.md
├── frontend/
│   ├── web/
│   │   ├── index.html
│   │   ├── app.js           # JavaScript web application
│   │   └── styles.css       # Styling
│   └── pubspec.yaml         # Dart dependencies (legacy)
└── README.md

Local dev vs Amplify deploy

• Local / CLI: Use the Flask backend in backend/. Run ./run.sh (or run.bat); the API and frontend are at http://localhost:5002. The CLI and web app read/write dictionary.json on disk.
• Amplify deploy: The frontend is built from frontend/web (see amplify.yml). The API is the Node/TypeScript app in backend-ts/, deployed as Amplify backend (Lambda + API Gateway), with the dictionary stored in S3. In Amplify, configure a rewrite so /api/* is proxied to that API. The Flask backend is not used in production.

JSON Database Format

The dictionary is stored as a JSON array with proper formatting for manual editing:

[
  {
    "term": "example",
    "definition": "a thing characteristic of its kind"
  },
  {
    "term": "another",
    "definition": "one more"
  }
]

If a term is added without a definition (via the web UI, API, or CLI), its definition will automatically be set to:

I didn't get that

API Endpoints

• GET /api/all - Get all dictionary entries
• GET /api/search?q=<query> - Search terms/definitions
• GET /api/terms?letter=<A-Z> - Get terms filtered by first letter
• GET /api/letters - Get list of available first letters
• POST /api/terms - Add new term
• PUT /api/terms/<term> - Update term definition
• DELETE /api/terms/<term> - Delete term (creates backup)
• POST /api/define-with-ai - Generate definition using Perplexity AI