ai-teacher/specs/003-basic-login/plan.md

Implementation Plan: Basic Login Protection

Branch: 003-basic-login | Date: 2026-04-06 | Spec: spec.md
Input: Feature specification from /specs/003-basic-login/spec.md

Summary

Add a login page to the Vue frontend so users must enter a username and password before accessing any route. The backend already has Spring Security with HTTP Basic Auth fully configured; credentials are validated on every API call. The implementation introduces a Pinia auth store that holds the entered credentials in sessionStorage, an axios interceptor that injects them on every request, a /login route with a login form, router guards that redirect unauthenticated users, and a logout button in the navbar. A lightweight /api/v1/auth/check endpoint is added to the backend to allow the frontend to verify credentials without side effects. Username is made configurable in the backend (currently hardcoded as "neurosurgeon").

Technical Context

Language/Version: Java 21 (backend) / TypeScript + Node 20 (frontend)
Primary Dependencies: Spring Boot 4.0.5, Spring Security (already included), Vue 3.4, Vue Router 4.3, Pinia 2.1, Axios 1.7
Storage: No new storage — credentials held in browser sessionStorage (frontend only)
Testing: Spring Boot Test (backend), Vitest (not yet set up — out of scope for this feature)
Target Platform: Web (SPA + REST API)
Project Type: Web application (backend API + Vue frontend client)
Performance Goals: Login response within 1 second under normal load
Constraints: No new backend dependencies; no database changes; must not break existing API surface
Scale/Scope: Small team (POC), single user role

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Principle	Status	Notes
I. KISS	PASS	HTTP Basic Auth is reused; no new auth protocol, no new dependencies. Frontend uses sessionStorage — no JWT, no refresh tokens.
II. Easy to Change	PASS	Auth store is a single Pinia store; swapping the auth mechanism later only requires updating the store and the SecurityConfig.
III. Web-First	PASS	Backend exposes REST endpoint; frontend is standalone SPA client. No server-side rendering added.
IV. Documentation as Architecture	PASS	README must be updated to show the login flow in the architecture diagram (same PR).
Technology Constraints	PASS	Still two deployable units (backend + frontend). No new service added.

Project Structure

Documentation (this feature)

specs/003-basic-login/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
│   └── auth.md
└── tasks.md             # Phase 2 output (/speckit.tasks — NOT created by /speckit.plan)

Source Code (repository root)

backend/
├── src/main/java/com/aiteacher/
│   ├── config/
│   │   └── SecurityConfig.java          # MODIFY: make username configurable
│   └── auth/
│       └── AuthController.java          # ADD: GET /api/v1/auth/check endpoint

frontend/
├── src/
│   ├── stores/
│   │   └── authStore.ts                 # ADD: Pinia store for credentials + session
│   ├── views/
│   │   └── LoginView.vue                # ADD: login form UI
│   ├── services/
│   │   └── api.ts                       # MODIFY: read credentials from authStore
│   ├── router/
│   │   └── index.ts                     # MODIFY: add /login route + navigation guard
│   └── App.vue                          # MODIFY: add logout button to navbar

Structure Decision: Option 2 (web application). Existing backend/ and frontend/ layout used; no new projects or packages.

Complexity Tracking

No constitution violations. Table left empty.