transfer_sms/plan.md

SMS Monitor - Implementation Plan

Context

A personal SMS monitoring system: an Android app monitors incoming/outgoing SMS and sends them to a server. The server stores them in SQLite with multi-user support. A web dashboard allows viewing/managing SMS. The user can configure auto-upload or manual-select modes.

Tech Stack Decisions

Layer	Choice	Rationale
Android App	Flutter	Best Material You support via dynamic_color, simple platform channels for SMS
Backend	Node.js + Express	Simplest, most documented
Database	SQLite (better-sqlite3)	Zero-config, fast sync API, perfect for single-server personal use
Web Dashboard	React + Vite	Lightweight SPA
Auth	JWT	Stateless, simple to implement

Project Structure

transfer_sms/
├── server/                    # Node.js backend
│   ├── package.json
│   ├── src/
│   │   ├── index.ts          # Entry point
│   │   ├── db.ts             # SQLite setup & migrations
│   │   ├── middleware/
│   │   │   └── auth.ts       # JWT auth middleware
│   │   ├── routes/
│   │   │   ├── auth.ts       # Register/Login
│   │   │   ├── sms.ts        # SMS CRUD endpoints
│   │   │   └── devices.ts    # Device registration
│   │   └── types.ts          # TypeScript types
│   └── tsconfig.json
├── web/                       # React web dashboard
│   ├── package.json
│   ├── vite.config.ts
│   └── src/
│       ├── App.tsx
│       ├── api.ts             # API client
│       ├── pages/
│       │   ├── Login.tsx
│       │   └── SmsList.tsx
│       └── components/
└── app/                       # Flutter Android app
    └── (flutter project)

Database Schema

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE sms_messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL REFERENCES users(id),
    phone_number TEXT NOT NULL,
    contact_name TEXT,
    content TEXT NOT NULL,
    type TEXT NOT NULL CHECK(type IN ('received', 'sent')),
    sms_date DATETIME NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_sms_user ON sms_messages(user_id, sms_date);
CREATE TABLE devices (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL REFERENCES users(id),
    device_name TEXT NOT NULL,
    last_sync_at DATETIME
);

API Endpoints

Method	Path	Auth	Description
POST	/api/auth/register	No	Create account
POST	/api/auth/login	No	Get JWT token
POST	/api/sms/upload	Yes	Batch upload SMS (array)
GET	/api/sms	Yes	Paginated list, filter by phone/date/type
GET	/api/sms/:id	Yes	Single SMS detail
DELETE	/api/sms/:id	Yes	Delete one SMS
POST	/api/devices/register	Yes	Register a device

Flutter App Design

SMS Access

• Use flutter_sms_listener or platform channel to native ContentResolver
• On Android: query content://sms ContentProvider, use Telephony.Sms broadcast receiver for real-time

Material You Theming

• dynamic_color package extracts system color scheme
• MaterialApp(theme: ThemeData(useMaterial3: true))

Upload Modes

• Auto mode: Background listener catches new SMS → immediately POSTs to server
• Manual mode: UI lists unsent SMS → user selects → taps "Upload"
• Mode toggle in settings screen

Screens

1. SMS List - All SMS, filterable, with sync status indicators
2. Settings - Server URL, auth token, upload mode toggle
3. Login - Server credentials

Web Dashboard Design

Pages

1. Login - Username + password
2. SMS List - Table with search/filter, pagination
3. SMS Detail - Single message view

Styling

• CSS custom properties for Material You color tokens
• Responsive design

Implementation Order

1. Server (backend first, everything depends on it)
   • Database setup + migrations
   • Auth routes (register/login)
   • SMS routes (upload/list/get/delete)
2. Web Dashboard (easiest to test against live server)
   • Login page
   • SMS list with pagination & filters
3. Flutter App (needs real device for SMS testing)
   • Project scaffold + Material You theme
   • SMS native access layer
   • Upload logic (auto + manual)
   • UI screens

Verification

1. Start server: cd server && npm run dev
2. Register user via curl: curl -X POST localhost:3000/api/auth/register -H "Content-Type: application/json" -d '{"username":"test","password":"123456"}'
3. Login to get token
4. Upload test SMS via curl with token
5. Open web dashboard, login, verify SMS appear
6. Build & run Flutter app on Android device, verify SMS sync