From 0bd38fed04b9081e6a4fae54dbfec5c5a6f57030 Mon Sep 17 00:00:00 2001
From: Andrew Ridgway <ar17787@gmail.com>
Date: Sat, 18 Jul 2026 23:40:03 +1000
Subject: [PATCH] docs: add README with project overview, auth flow, and build
 instructions

---
 README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..abd9cec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,123 @@
+# ResBuilder Android
+
+Native Android client for [ResBuilder AI](https://git.aridgwayweb.com/armistace/resbuilder_ai) — an AI-powered resume and cover letter generator.
+
+## Overview
+
+This app connects to the ResBuilder backend API to let users:
+- Authenticate via Google Sign-In
+- Paste or scrape job descriptions (including SEEK URLs)
+- Upload existing resumes/cover letters (PDF/DOCX)
+- Submit AI generation jobs
+- View generated documents as rendered HTML
+- Export results as PDF or DOCX
+
+## Architecture
+
+```
+com.example.resbuilder
+├── data
+│   ├── model          # Pydantic-style data classes (User, Job, etc.)
+│   └── remote         # OkHttp API client with Bearer token auth
+└── ui
+    ├── LoginActivity      # Google Sign-In via Credential Manager
+    ├── MainActivity       # Tab navigation + fragment container
+    ├── JobFormFragment    # Job details, upload, scrape, submit
+    ├── JobStatusFragment  # Poll job status (2s interval, 10min max)
+    ├── ResultFragment     # HTML preview, copy, export
+    └── AdminActivity      # Admin user management (optional)
+```
+
+## Authentication
+
+Uses **Google Sign-In for Android** (compliant with Google OAuth policy):
+1. User taps Sign In → native Google account picker
+2. App receives a Google ID token
+3. Token is exchanged for a backend session token via `POST /auth/google-token`
+4. Session token is sent as `Authorization: Bearer <token>` on every API call
+
+No WebView. No embedded user-agents. No cookies.
+
+## Requirements
+
+- Android SDK 29+ (Android 10)
+- Compile SDK 36
+- Java 11
+- Gradle 9.4.1
+
+## Dependencies
+
+| Library | Purpose |
+|---------|---------|
+| OkHttp 4.12.0 | HTTP client, cookie jar, interceptor |
+| Gson 2.10.1 | JSON serialization |
+| Material Components 1.10.0 | UI components (M3) |
+| Play Services Auth 20.7.0 | Google Sign-In |
+
+## Configuration
+
+Set your Google Web Client ID in `LoginActivity.kt`:
+
+```kotlin
+private val webClientId = "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com"
+```
+
+This must match the `GOOGLE_CLIENT_ID` configured on the backend.
+
+## Build
+
+```bash
+./gradlew assembleDebug
+```
+
+APK output: `app/build/outputs/apk/debug/app-debug.apk`
+
+## API
+
+The app talks to `https://resume.aridgwayweb.com` (configurable in `ApiClient.kt`).
+
+Key endpoints used:
+- `POST /auth/google-token` — exchange Google ID token for session
+- `GET /auth/me` — current user info
+- `POST /build_resume` | `/build_cover_letter` — submit generation job
+- `GET /job/{id}` — poll job status
+- `POST /upload/resume` | `/upload/cover_letter` — extract text from PDF/DOCX
+- `POST /scrape-job` — extract text from SEEK URL
+- `GET /export/{id}/pdf` | `/export/{id}/docx` — download generated document
+
+## Project Structure
+
+```
+app/src/main/
+├── java/com/example/resbuilder/
+│   ├── data/
+│   │   ├── model/Models.kt
+│   │   └── remote/ApiClient.kt
+│   └── ui/
+│       ├── LoginActivity.kt
+│       ├── MainActivity.kt
+│       ├── JobFormFragment.kt
+│       ├── JobStatusFragment.kt
+│       ├── ResultFragment.kt
+│       ├── AdminActivity.kt
+│       └── AdminUserAdapter.kt
+├── res/layout/
+│   ├── activity_login.xml
+│   ├── activity_main.xml
+│   ├── fragment_job_form.xml
+│   ├── fragment_job_status.xml
+│   ├── fragment_result.xml
+│   └── activity_admin.xml
+└── res/values/
+    ├── colors.xml
+    ├── strings.xml
+    └── themes.xml
+```
+
+## Design System
+
+See `.agents/design/DESIGN.md` for the Material Design 3 + Amazon/Google design guidelines used across the app.
+
+## License
+
+Same as the backend project.