# 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
```sql
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