Skip to content

README.md

Latest commit

 

History

History
327 lines (236 loc) · 12.1 KB

README.md

File metadata and controls

327 lines (236 loc) · 12.1 KB
Raw

5★A Project

Project Structure

The repository contains two production‑ready applications:

  1. Nevai (5A_Search) – A privacy‑focused AI‑powered multi‑source search engine (Single Page Application).
  2. 5★A (Five Star A) – A full‑featured task and project management system with REST API, Chrome extension, and real‑time capabilities.
project-root/
├── 5A_Search/               # Nevai Search Engine application
├── 5A_Task_Management/      # 5★A Task Management System
├── master_dev_checklist.md  # Development checklist (1154 lines)
└── ...

Application 1: Nevai Search Engine (5A_Search)

Name: Nevai
Type: AI‑Powered Multi‑Source Search Engine
Architecture: Single Page Application (SPA)
Design Philosophy: Minimalist, privacy‑focused, no API keys required

Technology Stack

Technology Version Purpose
React 19 UI framework
TypeScript Latest Type safety and development experience
Vite Latest Build tool and dev server
Tailwind CSS 4 Styling framework
web‑llm Latest Local AI model execution
clsx Latest Conditional className utility
tailwind‑merge Latest Tailwind class merging

Core Features

  1. Multi‑Source Search Aggregation (20+ API Sources)

    • General Knowledge: DuckDuckGo, SearXNG, Wikipedia, Wikidata, DBpedia
    • Academic/Tech: Open Library, arXiv, Hacker News, GitHub, Dev.to
    • Social/Media: Reddit, iTunes, Deezer
    • Data Services: CoinGecko, OpenMeteo, RestCountries
    • Wikimedia: Wikiquote, Wikibooks, Wikivoyage, Wikisource, Wikiversity

  2. Search Categories

    • Web Search – General queries across multiple sources
    • News Search – Latest articles from news aggregators
    • Image Search – Visual content results
    • Instant Answers – Quick factual responses
    • Definitions – Word meanings and explanations
    • Weather Information – Location‑based weather data
    • Time and Date – World clock and timezone data
    • Translations – Multi‑language translation support

  3. AI‑Powered Features

    • Runs entirely in the browser using WebAssembly (local LLM execution)
    • No data sent to external servers – complete privacy
    • AI chat with context‑aware responses
    • Generates search result summaries, answers follow‑up questions, explains complex topics, compares results, extracts key information
    • Configurable model through web-llm

  4. User Interface Features

    • Clean, minimal search interface
    • Category quick access grid
    • Dark/light theme toggle
    • Keyboard navigation support
    • Tabbed interface for different result types
    • AI summary cards
    • Bookmark functionality
    • Result filtering and sorting
    • Pagination support
    • Command palette (keyboard shortcuts)
    • Bookmarks panel, category browser, newsletter subscription

  5. Security Features

    • Input sanitization: XSS prevention, SQL injection protection, script tag filtering, URL validation
    • Console security: console locking mechanism, self‑XSS warning messages
    • Security headers: Content Security Policy checking, HTTPS enforcement, referrer policy validation

  6. User Experience

    • URL bookmarkable searches (query parameters)
    • Browser history integration
    • Local storage for preferences
    • Dark mode with system preference detection
    • Mobile‑responsive design
    • PWA‑ready (Progressive Web App)
    • Offline capability planning

  7. Performance

    • Code splitting
    • Lazy loading of components
    • Optimized bundle size
    • Fast initial load time

File Structure (Nevai)

5A_Search/
├── package.json
├── package-lock.json
├── tsconfig.json
├── index.html
├── run.sh
└── shell-command-count

Application 2: 5★A Task Management System

Type: Full‑stack task and project management platform
Components: REST API backend, Vanilla JavaScript frontend, Chrome Extension
Design: Minimalist Zara‑inspired black and white aesthetic

Backend Technology Stack

Technology Purpose
Python 3.11+ Programming language
FastAPI Web framework
SQLAlchemy 2.0+ ORM
PostgreSQL 15 Primary database
Redis 7 Caching and rate limiting
Pydantic 2.0+ Data validation
python‑jose JWT handling
passlib/bcrypt Password hashing
pyotp TOTP 2FA
spacy/dataparser NLP parsing

Frontend Technology

Technology Purpose
Vanilla JavaScript Core logic
HTML5/CSS3 Markup and styling
Cormorant Garamond Primary font
Space Grotesk Secondary font

User Roles and Permissions

Feature Admin PM Employee
Create Users Yes No No
Create Projects Yes Yes No
Assign Tasks Yes Yes No
Update Any Task Yes Yes No
Update Own Task Yes Yes Yes
View Team Analytics Yes Yes No
Export Data Yes Yes Yes (own)

Database Tables (21 Total)

Table Purpose
users User accounts and profiles
oauth_accounts OAuth provider connections
projects Project definitions
tasks Task definitions
task_attachments Task file attachments
task_comments Task comments
labels Label definitions
collections Project collections
notifications User notifications
integrations Third‑party integrations
... (other tables)

Key API Endpoints (100+ Total)

Authentication (6)

  • POST /auth/register, POST /auth/login, POST /auth/refresh, POST /auth/2fa/setup, POST /auth/2fa/verify, POST /auth/logout

Users (6)

  • GET /users, GET /users/me, GET /users/{id}, PUT /users/{id}, DELETE /users/{id}, GET /users/search

Projects (7)

  • GET /projects, POST /projects, GET /projects/{id}, PUT /projects/{id}, DELETE /projects/{id}, POST /projects/{id}/share, POST /projects/{id}/duplicate

Tasks (12)

  • GET /tasks, POST /tasks, GET /tasks/{id}, PUT /tasks/{id}, DELETE /tasks/{id}, PATCH /tasks/{id}/status, POST /tasks/{id}/assign, POST /tasks/voice, POST /tasks/email, POST /tasks/{id}/recurrence/run, GET /tasks/search, POST /tasks/bulk

Labels (4)

  • GET /labels, POST /labels, PUT /labels/{id}, DELETE /labels/{id}

Collections (4)

  • GET /collections, POST /collections, PUT /collections/{id}, DELETE /collections/{id}

Notifications (5)

  • GET /notifications, PATCH /notifications/{id}/read, POST /notifications/read-all, DELETE /notifications/{id}, WebSocket /notifications/stream

Analytics (5)

  • GET /analytics/productivity, GET /analytics/weekly, GET /analytics/monthly, GET /analytics/trends, GET /analytics/team

Export (3)

  • GET /export/tasks/json, GET /export/tasks/csv, GET /export/analytics

Focus (7)

  • GET /focus/weather, POST /focus/pomodoro/start, POST /focus/pomodoro/{id}/complete, GET /focus/pomodoro/history, GET /focus/goals, POST /focus/goals, POST /focus/goals/{id}/complete

Views (10)

  • GET /views/dashboard, GET /views/list, GET /views/kanban, GET /views/calendar, GET /views/matrix, GET /views/map, GET /views/grid, GET /views/planner, GET /views/skyline, GET /views/stream

Comments (4)

  • GET /tasks/{id}/comments, POST /tasks/{id}/comments, PUT /comments/{id}, DELETE /comments/{id}

Attachments (3)

  • POST /tasks/{id}/attachments, GET /attachments/{id}, DELETE /attachments/{id}

Friends (4)

  • GET /friends, POST /friends/request, POST /friends/accept, POST /friends/block

Password Reset (2)

  • POST /password-reset/request, POST /password-reset/confirm

Integrations (5)

  • GET /integrations, POST /integrations/spotify, POST /integrations/calendar/sync, GET /integrations/spotify/playlists, POST /integrations/spotify/play

System (2)

  • GET /health, GET /openapi.json

10 View Engines

View Key Features
List Sortable columns, inline editing, bulk selection, CSV export
Kanban Drag‑drop between columns, WIP limits, card details on hover
Calendar Month/week/day views, drag to reschedule, multi‑day events
Matrix Eisenhower quadrants, urgency vs importance scoring
Map Geolocation display, interactive map, task markers
Grid Visual card layout, customizable columns, quick actions
Planner Timeline visualization, dependency tracking, milestones
Skyline Workload visualization, capacity planning, resource allocation
Stream Activity feed, real‑time updates, notification integration
Workload Team capacity analysis, task distribution, overload alerts

Testing Results

Metric Value
Total Tests 54
Passing Tests 52
Pass Rate 96.3%
Average Coverage 73%

Deployment Configuration (Docker Compose)

Service Image Port Purpose
postgres postgres:15‑alpine 5432 Primary database
redis redis:7‑alpine 6379 Caching and rate limiting
backend custom build 8000 FastAPI application

Environment Variables

Variable Purpose
DATABASE_URL Database connection string
REDIS_URL Redis connection string
SECRET_KEY JWT signing key
ACCESS_TOKEN_EXPIRE_MINUTES Access token lifetime
CORS_ORIGINS Allowed CORS origins

Rate Limiting

Setting Value
Requests per minute 100
Window duration 60 seconds
Exempt paths /health, /docs, /openapi.json, /redoc
Exceeded response HTTP 429 with Retry‑After header
  • Core authentication (register, login, 2FA, OAuth)
  • User management
  • Project CRUD operations
  • Task management with status validation
  • 10 view engines (List, Kanban, Calendar, Matrix, Map, Grid, Planner, Skyline, Stream, Workload)
  • Real‑time WebSocket notifications
  • Analytics and reporting (productivity, weekly, monthly, trends, team)
  • Export functionality (CSV, JSON)
  • Focus panel widgets (Pomodoro, weather, goals)
  • Chrome extension
  • Friend system
  • Password reset
  • Rate limiting
  • Database migrations (Alembic)
  • Test suite (96.3% pass rate)
  • Docker deployment
  • Nevai search engine integration
  • Nevai: A privacy‑first AI search engine that aggregates 20+ sources with local LLM capabilities via WebAssembly, requiring no API keys.
  • 5★A Task Manager: A full‑stack system with FastAPI backend, PostgreSQL, Redis, role‑based access, 10 view engines, real‑time updates, and 100+ API endpoints.

.