Quiet Brew Shield MVP

ハッカソンチーム: コーヒー愛好会

Scope

• Single source of truth: docs/requirements_for_cli.md
• MVP: X-only, variable session, JA/EN analysis, manual start fallback
• Frontend: Next.js (PWA-ready)
• Backend: Python FastAPI (Vertex AI SDK + X API v2 adapter)

Run backend

python -m venv backend/.venv
.\backend\.venv\Scripts\python -m pip install -r backend/requirements.txt
$env:PYTHONPATH='backend'
.\backend\.venv\Scripts\python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Run frontend

cd frontend
npm install
npm run dev

Create local env for frontend API base URL:

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000

File: frontend/.env.local

Open: http://127.0.0.1:3000

Real X + Vertex AI

Set backend/.env from backend/.env.example and enable real APIs.

USE_REAL_APIS=true
X_BEARER_TOKEN=...
# Provide one of these per request from frontend/user input:
# x_username=@yourname  (recommended)
# x_user_id=1234567890
X_TIMELINE_MODE=user
X_MAX_RESULTS=20
VERTEX_PROJECT_ID=your-gcp-project
VERTEX_LOCATION=us-central1
GOOGLE_API_KEY=your-google-api-key
GEMINI_FLASH_MODEL=models/gemini-flash-latest
GEMINI_PRO_MODEL=models/gemini-pro-latest
X_OAUTH_CLIENT_ID=your-x-oauth-client-id
X_OAUTH_CLIENT_SECRET=your-x-oauth-client-secret
X_OAUTH_REDIRECT_URI=http://127.0.0.1:8000/api/auth/x/callback
FRONTEND_BASE_URL=http://127.0.0.1:3000

Vertex AI uses Application Default Credentials. On local development, run:

gcloud auth application-default login

Example analysis request:

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/api/session/end `
  -ContentType "application/json" `
  -Body '{"session_id":"YOUR_SESSION_ID","timeline_mode":"user","x_username":"googledevjp","max_results":10}'

/api/session/end now requires x_username or x_user_id in the request body.

For home timeline mode, first sign in with X from the frontend. The backend stores the OAuth session in an HttpOnly cookie, so oauth_token_id is no longer sent to the frontend.

Minimal OAuth 2.0 PKCE (in progress)

• GET /api/auth/x/login: returns authorization URL and state
• POST /api/auth/x/callback: exchanges code + state for backend session metadata
• GET /api/auth/x/callback: accepts redirect from X, sets an HttpOnly cookie, and sends the user to the frontend callback page
• GET /api/auth/x/session: returns current login status for the frontend
• POST /api/auth/x/logout: clears the backend OAuth session
• /api/session/end with timeline_mode="home" now reads the authenticated session from the cookie

OAuth token records are stored server-side in SQLite (oauth_tokens table) and removed after expiry by cleanup. Refresh tokens are not persisted.

Frontend now has a ホーム mode button. Press Xでログイン first, then start scanning. Frontend callback page: /oauth/x/callback

Demo mode / fallback

• Default .env: USE_REAL_APIS=false
• This intentionally forces fallback fixed data, so demo always continues.

Tests

$env:PYTHONPATH='backend'
.\backend\.venv\Scripts\python -m pytest backend/tests -q