Skip to content

TECHNICAL_DOCS.md

Latest commit

 

History

History
128 lines (105 loc) · 6.59 KB

TECHNICAL_DOCS.md

File metadata and controls

128 lines (105 loc) · 6.59 KB

Technical Documentation for OmniRemindersV2

1. Project Overview

OmniRemindersV2 is a web-based application designed to help users manage their reminders and recurring tasks efficiently. The application provides a clean user interface to create, view, edit, and delete reminders. It features a dashboard for a quick overview, a detailed list of all reminders, and a calendar view for a monthly perspective.

The application is built with a modern tech stack, featuring a React frontend and a Node.js (Express) backend. It is containerized using Docker for easy setup and deployment. Key features include AI-powered reminder creation from natural language, reminder analysis, and a notification system for upcoming reminders via email and Gotify.

2. Tech Stack

Frontend

  • Framework: React (v19) with Vite
  • Language: TypeScript
  • Styling:
    • Bootstrap & React-Bootstrap: For UI components and layout.
    • lucide-react: For icons.
  • Routing: React Router DOM (v7)
  • HTTP Client: Axios
  • State Management: React Context API (for theme)
  • Data Visualization: Recharts (for charts on the dashboard)
  • Calendar/Date: react-calendar and react-datepicker

Backend

  • Framework: Express.js on Node.js
  • Language: JavaScript (ES Modules)
  • API: RESTful
  • Database: Simple file-based storage (JSON files in the /data directory).
    • reminders.json: Stores all reminder data.
    • settings.json: Stores application and notification settings.
  • AI Integration:
    • Groq SDK (groq-sdk): For natural language processing to parse and create reminders.
  • Authentication:
    • JSON Web Tokens (JWT): For securing API endpoints.
    • google-auth-library: For backend verification of Google OAuth tokens.
  • Notifications:
    • Nodemailer: For sending email notifications.
    • Gotify: For sending push notifications (via Axios).
  • Scheduling: node-cron: For scheduling daily checks for upcoming reminders.

Development & Deployment

  • Containerization: Docker & Docker Compose
  • Web Server: The Express server also serves the static React build.

3. Project Structure

The project is organized into two main directories: client and server.

/
├── client/              # React frontend application
│   ├── src/
│   │   ├── components/  # Reusable React components
│   │   ├── context/     # React context providers (e.g., ThemeContext)
│   │   ├── pages/       # Top-level page components (Dashboard, Reminders, etc.)
│   │   └── App.tsx      # Main app component with routing
│   ├── package.json
│   └── vite.config.ts
├── server/              # Node.js Express backend
│   ├── routes/          # (currently empty, routes are in index.js)
│   ├── index.js         # Main server entry point with all API logic
│   ├── db.js            # Handles all interactions with the JSON database
│   └── package.json
├── data/                # Persisted data (created on run)
│   ├── reminders.json
│   └── settings.json
├── Dockerfile           # Multi-stage Dockerfile for building and running the app
├── docker-compose.yml   # Docker Compose for local development
└── TECHNICAL_DOCS.md    # This file

4. Getting Started

Prerequisites

  • Docker and Docker Compose installed and running.

Running the Application

  1. Clone the repository.
  2. From the project root, run the following command: 
    docker-compose up -d --build
  3. The application will be available at http://localhost:5006.

The docker-compose.yml configuration builds the Docker image using the Dockerfile and mounts the ./data directory to persist application data.

5. Core Features & Logic

Reminder Management

  • CRUD Operations: The backend provides API endpoints to Create, Read, Update, and Delete reminders. These operations are handled in server/db.js and exposed via Express routes in server/index.js.
  • Data Storage: Reminders are stored in data/reminders.json, with each reminder having a unique ID generated by crypto.randomUUID().

AI Integration

  • AI Reminder Creation (/api/ai/create-reminder):
    • Takes a natural language string (e.g., "Call dad next Tuesday").
    • Uses the Groq API to parse the string into a structured JSON object representing the reminder.
    • The backend validates the AI's output and saves the new reminder.
  • AI Analysis (/api/ai/analyze):
    • This endpoint sends all active reminders to the Groq API.
    • It asks for a summary, suggestions for better management, and an assessment of category distribution.

Notifications

  • Scheduled Checks: A cron job is scheduled using node-cron to run a daily check for reminders that are due soon (within the next 3 days).
  • Notification Channels: If upcoming reminders are found, the system can send notifications via:
    • Email: Using Nodemailer. SMTP server details are configured in the settings.
    • Gotify: A self-hostable push notification service. The Gotify URL and token are configured in the settings.
  • Configuration: All notification settings (SMTP, Gotify, and a master enable/disable toggle) are managed through the Settings page and stored in data/settings.json.

6. API Endpoints

All endpoints are prefixed with /api.

  • GET /reminders: Fetches all reminders.
  • POST /reminders: Saves a new reminder or updates an existing one.
  • DELETE /reminders/:id: Deletes a reminder by its ID.
  • GET /settings: Retrieves the current application settings.
  • POST /settings: Updates the application settings.
  • POST /ai/analyze: Triggers the AI analysis of active reminders.
  • POST /ai/create-reminder: Creates a new reminder from natural language text.
  • POST /convert-tamil-date: A utility endpoint to convert a Tamil calendar date to a Gregorian date.
  • POST /test/*: A set of endpoints for testing notification channels (email, Gotify) and the reminder check logic.

7. Frontend Architecture

  • Component-Based: The UI is built with reusable React components located in src/components.
  • Page-Based Routing: react-router-dom maps URLs to specific page components in src/pages.
  • Main Layout: A consistent layout (AppLayout.tsx) provides the navbar and sidebar, wrapping the content of each page.
  • Data Fetching: Components fetch data from the backend API using Axios. For example, the Reminders.tsx page fetches all reminders on load to display them in a table.
  • Modal for Editing/Creation: The ReminderModal.tsx component is used for both creating new reminders and editing existing ones.