AI_PROJECT_CONTEXT.md

AI Project Context Document

This document provides comprehensive context for AI systems to understand the "My Dashboard" project. It includes project goals, architecture, technology stack, current implementation status, and links to detailed documentation.

Project Overview

Project Name: My Dashboard Description: A dashboard management system for displaying information on old Android phones. Users create dashboards through a web application, add widgets, and bind phones via QR code. The phone receives data through an API and displays widgets in real-time. Live Demo: https://site15-my-dashboard.vercel.app

Project Structure

The project consists of two main components:

1. Mobile Application (/mobile)

   • Framework: Ionic-Angular with Capacitor for Android support
   • Build system: Ionic + Capacitor
   • Target platform: Android
   • Navigation: Tab-based (tab1, tab2, tab3)

2. Web Application (/web)

   • Framework: AnalogJS (Angular-based fullstack framework)
   • Backend: Server routes in /src/server
   • Database: Prisma ORM with PostgreSQL
   • API: tRPC for type-safe communication
   • Deployment: Vercel

Technology Stack

Web Application

• Frontend: AnalogJS, Angular, tRPC client
• Backend: AnalogJS server routes, tRPC server
• Database: Prisma ORM, PostgreSQL
• Styling: Pico.css, Tailwind CSS
• Authentication: Telegram OAuth
• Deployment: Vercel

Mobile Application

• Framework: Ionic-Angular
• Native Integration: Capacitor
• UI Components: Ionic UI library
• Target: Android

Shared Technologies

• Language: TypeScript
• Build Tool: npm
• Testing: Vitest
• Database: PostgreSQL (Neon recommended)

Database Schema

See detailed schema in schema.prisma:

• User: id, anonymousId, telegramUserId, telegramUserData, isBlackTheme, Session[], Dashboard[]
• Session: id, userId, createdAt, deletedAt
• Dashboard: id, name, deviceId, userId, isBlackTheme, Widget[]
• Widget: id, options (JSON), state (JSON), grid positioning, colors, dashboardId
• WidgetLog: id, oldOptions, newOptions, oldState, newState, widgetId

Current Implementation Status

Completed Components

1. Project infrastructure (AnalogJS, Ionic, Prisma)
2. Database schema implementation
3. Telegram authentication system
4. Basic web UI (login, dashboard list, dashboard view, device linking)
5. QR code generation for device linking
6. Vercel deployment configuration
7. GitHub Actions workflow for mobile builds

Pending Components

1. Email/password registration
2. Anonymous mode with localStorage
3. User reattachment functionality
4. Full Dashboard CRUD operations
5. Widget CRUD operations
6. Partial implementation of Habits Tracking Widget
7. Mobile QR code scanning
8. Widget display components on mobile
9. Real-time widget updates
10. Widget state management
11. Offline caching for mobile
12. Usage metrics collection

Development Plan

See detailed task tracking in:

• PROJECT_TASKS.md (English)
• PROJECT_TASKS_RU.md (Russian)

Sprint 1 (2025-11-12 – 2025-11-17)

Focus: Complete core functionality for basic dashboard management

Sprint 2 (2025-11-18 – 2025-11-24)

Focus: Implement mobile application and full integration

Key Files and Directories

Web Application

• schema.prisma - Database schema
• vite.config.ts - Vite configuration
• package.json - Dependencies and scripts
• src/app/ - Frontend components
• src/server/ - Backend routes and logic
• src/server/trpc/routers/ - tRPC API endpoints

Mobile Application

• capacitor.config.ts - Capacitor configuration
• ionic.config.json - Ionic configuration
• package.json - Dependencies and scripts
• src/app/ - Application source code

API Endpoints

tRPC Routes

• /users - User management
• /telegram - Telegram authentication
• /auth - Authentication operations
• /dashboards - Dashboard operations
• /widgets - Widget operations

See implementation in src/server/trpc/routers/

Authentication System

The web application uses Telegram authentication with:

• Redirect method
• Server-side hash verification
• Tunneling via tuna.am for local development

See Telegram Authentication Integration for details.

Development Environment

Prerequisites

• Node.js 22.x
• PostgreSQL database (Neon recommended)
• Telegram bot for authentication (optional for local development)

Environment Variables

MY_DASHBOARD_DATABASE_POSTGRES_URL=postgresql_connection_string

Running Applications

Web Application

cd web
npm install
npm start

Mobile Application

cd mobile
npm install
ionic serve

Deployment

Web Application

• Platform: Vercel
• Database: Neon PostgreSQL (native integration)
• URL: https://site15-my-dashboard.vercel.app

Mobile Application

• Platform: Android APK
• Build: GitHub Actions workflow
• Distribution: Manual

Detailed Documentation

For comprehensive project information, refer to:

• PROJECT_OVERVIEW.md - Technical specification and implementation plan
• TECHNICAL_DOCUMENTATION.md - Detailed technical documentation
• README.md - Root project documentation
• web/README.md - Web application documentation
• mobile/README.md - Mobile application documentation

Troubleshooting

Common issues and solutions:

1. "Bot domain invalid" - Configure bot domain via BotFather
2. "Blocked request" - Add domain to vite.config.ts allowedHosts

See Troubleshooting for detailed solutions.