Phase 1 comlpletes

Author: Shashankpgit

.gitignore

@@ -0,0 +1,28 @@
+# Environment
+.env
+vault/.env
+vault/.venv/
+vault/venv/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Database (local dev only)
+vault/vault.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/

claude-instructions/README.md

@@ -0,0 +1,190 @@
+# Claude Master Instructions — Personal Vault Project
+
+This file is Claude's primary reference document. Read this at the start of every session before doing anything.
+
+---
+
+## Application: Personal Vault
+
+A multi-user, private data storage application. Users register, log in, and store their own private data that no other user can see.
+
+### What a user can do
+- Register with a username and password
+- Log in and receive a session token
+- Store **text notes** (title + body)
+- Store **passwords** (label + username + password value)
+- Store **important notes** (tagged, searchable)
+- View, edit, and delete only their own data
+
+### Real-world analogy
+Think of it as a personal, self-hosted combination of Bitwarden (password manager) and a private notebook. Bob logs in and sees only Bob's data. Alice logs in and sees only Alice's data.
+
+---
+
+## Version Strategy
+
+| Version | Scope | Phases |
+|---|---|---|
+| v1 | API only, SQLite, no authentication | Phase 1–2 |
+| v2 | Authentication added, multi-user, PostgreSQL | Phase 3–4 |
+| v3 | Minimal frontend, DevTools learning | Phase 3 |
+| v4 | Architecture refactor (service + repo layers) | Phase 5 |
+| v5 | Containerized, Dockerized | Phase 6 |
+| v6 | Nginx reverse proxy | Phase 7 |
+| v7 | Kong API gateway | Phase 8 |
+| v8 | Keycloak SSO replaces custom JWT | Phase 9 |
+| v9 | Kubernetes deployment | Phase 10 |
+| v10 | Helm charts | Phase 11 |
+| v11 | CI/CD pipeline | Phase 12 |
+| v12 | Monitoring and logging | Phase 13 |
+
+---
+
+## Tech Stack
+
+| Layer | Choice | Reason |
+|---|---|---|
+| Language | Python 3.11+ | User has prior Python knowledge |
+| API Framework | FastAPI | User knows basics; auto-docs at /docs; async |
+| Database (v1) | SQLite | Zero setup; perfect for learning |
+| Database (v2+) | PostgreSQL | Production-grade; migrate before Docker |
+| ORM | SQLAlchemy 2.x | Industry standard; works with both DBs |
+| Migrations | Alembic | Tracks schema changes like git does for code |
+| Auth | Custom JWT first, then Keycloak | Learn JWT internals before enterprise SSO |
+| Frontend | Plain HTML + vanilla JS (no framework) | Learn fundamentals before React |
+| Container | Docker + docker-compose | Learn containers before Kubernetes |
+| Reverse Proxy | Nginx | Industry standard reverse proxy |
+| API Gateway | Kong | Real-world API management layer |
+| Orchestration | Kubernetes | After Docker fundamentals are solid |
+| Package manager | pip + requirements.txt → Poetry | Start simple, evolve tooling |
+
+---
+
+## Phase Roadmap
+
+```
+Phase 1  → Project setup + first API endpoint + database connection
+Phase 2  → Full CRUD: notes, passwords, user model (no auth yet)
+Phase 3  → Minimal HTML frontend + Chrome DevTools introduction
+Phase 4  → CORS + JWT authentication + auth middleware
+Phase 5  → Service layer + Repository pattern (architecture refactor)
+Phase 6  → Docker + docker-compose
+Phase 7  → Nginx reverse proxy
+Phase 8  → Kong API gateway
+Phase 9  → Keycloak (replace custom JWT)
+Phase 10 → Kubernetes (pods, deployments, services)
+Phase 11 → Helm charts
+Phase 12 → GitHub Actions CI/CD
+Phase 13 → Prometheus + Grafana + structured logging
+```
+
+---
+
+## Non-Negotiable Process Rules
+
+Claude MUST follow these rules in every session without exception.
+
+### Rule 1 — Docs structure
+Every `docs/NNN-*.md` file must have exactly two parts:
+
+**Part 1: What we are doing** — files being created/modified, implementation steps, what is NOT in scope for this step.
+
+**Part 2: Concepts / KT** — short explanation of every tool, pattern, or technology used in this step. Not a textbook. Just enough to understand why it exists and what role it plays. Written in plain language with short examples.
+
+### Rule 2 — Explain WHY first
+Before implementing, explain the business reason and technical reason. Not just "we are adding X" but "we are adding X because Y problem exists."
+
+### Rule 3 — One small step at a time
+Never implement an entire feature in one shot. Break it into the smallest logical steps. Example: adding auth = 6 separate steps, not 1.
+
+### Rule 4 — Teach during implementation
+When a concept appears in code, explain it inline. Do not dump theory upfront. JWT appears in code → explain JWT then.
+
+### Rule 5 — Never skip a phase
+Do not jump from Phase 1 to Phase 4. Every phase has a learning purpose. Respect the sequence.
+
+### Rule 6 — Real engineering practices always
+Even in v1 (SQLite, no auth), always use:
+- Proper folder structure
+- Environment variables (never hardcode secrets)
+- Consistent naming conventions
+- Meaningful error responses
+- Git commits after every logical step
+
+### Rule 7 — Frontend is last in each phase
+Only build frontend after the backend step in that phase is stable and manually tested via `/docs` (FastAPI's swagger UI).
+
+### Rule 8 — KT docs on demand
+If the user says "I don't understand" or "create KT document" — immediately create `docs/KT-topic-name.md` using the structure defined in goal.md.
+
+---
+
+## Folder Structure (target for v1)
+
+```
+development/                     ← git repo root
+├── claude-instructions/         ← Claude's playbooks (this directory)
+├── docs/                        ← all planning + KT documents
+├── goal.md                      ← learning goals and mentorship rules
+├── README.md
+├── .gitignore
+└── vault/                       ← the actual application lives here
+    ├── app/
+    │   ├── main.py              ← FastAPI app entry point
+    │   ├── config.py            ← environment + settings
+    │   ├── database.py          ← DB engine + session setup
+    │   ├── models/              ← SQLAlchemy ORM models
+    │   ├── schemas/             ← Pydantic request/response schemas
+    │   ├── routers/             ← FastAPI route handlers
+    │   ├── services/            ← business logic (added in Phase 5)
+    │   └── repositories/        ← DB access layer (added in Phase 5)
+    ├── tests/                   ← pytest tests
+    ├── .env                     ← local environment variables (gitignored)
+    ├── .env.example             ← committed template of env vars
+    └── requirements.txt
+```
+
+**Rule:** All application code lives inside `vault/`. All docs, plans, and Claude instructions live at the repo root level. Never mix them.
+
+---
+
+## Application Data Models (target)
+
+### User
+- id, username (unique), hashed_password, created_at
+
+### Note
+- id, user_id (FK), title, body, created_at, updated_at
+
+### Password Entry
+- id, user_id (FK), label, username, encrypted_value, created_at
+
+### Tag (future, Phase 2+)
+- id, name, user_id
+
+---
+
+## DevTools Learning Goals
+
+The user has never used browser developer tools. These concepts should be taught progressively during Phase 3:
+- Network tab: observe HTTP requests, status codes, headers, request/response bodies
+- Console tab: JavaScript errors, console.log debugging
+- Elements tab: inspect HTML structure
+- Application tab: view localStorage, cookies, tokens stored in browser
+
+Tie every DevTools lesson to something that just happened in the app (e.g., "open Network tab and watch what happens when you click Save").
+
+---
+
+## Cloud + Domain Goal
+
+After Phase 6 (Docker), the project will be deployed to a cloud provider (to be decided) with a free domain. This simulates a real production deployment. Claude should keep this in mind when making infrastructure decisions — avoid anything that only works locally.
+
+---
+
+## Reference Files
+
+- `goal.md` — user's full learning goal and mentorship instructions
+- `claude-instructions/debugging-philosophy.md` — **READ THIS** for how to handle all errors and deliberate mistakes
+- `claude-instructions/phase-*/` — per-phase implementation playbooks
+- `docs/` — all feature planning docs and KT documents created during development

claude-instructions/debugging-philosophy.md

@@ -0,0 +1,161 @@
+# Debugging Philosophy
+
+This file defines how Claude handles errors and debugging throughout all phases.
+
+---
+
+## Rule: Teach debugging methodology BEFORE fixing anything
+
+When an error occurs — whether real or deliberately introduced — never silently fix it.
+
+Always follow this sequence:
+
+### 1. Read the error out loud
+Walk through the error message word by word. Most engineers (especially beginners) panic when they see a red error and immediately Google it without actually reading what it says.
+
+Example:
+```
+sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: notes
+```
+Before fixing: "Let's read this carefully. `OperationalError` — something went wrong at the database operation level. `no such table: notes` — the database doesn't have a table called `notes`. Why? Let's find out."
+
+### 2. Identify the layer
+Which layer is failing?
+- Is the error in the terminal (server-side)?
+- Is the error in the browser Console (client-side JavaScript)?
+- Is the error in the browser Network tab (HTTP response)?
+- Is the error in the database (SQL)?
+
+Knowing WHERE the error is tells you WHERE to look next.
+
+### 3. Form a hypothesis
+Before touching anything: "I think this is happening because X."
+Then check if that hypothesis is correct.
+
+### 4. Test the hypothesis (not fix it)
+One change at a time. If you change three things at once and it works, you don't know what fixed it — and you don't learn.
+
+### 5. Fix, then explain WHY the fix works
+Not just what the fix is, but why the original code was wrong and what the fix does differently.
+
+---
+
+## Deliberate Mistakes Policy
+
+At appropriate moments in each phase, Claude will intentionally introduce a common real-world mistake, let the error surface, and then run through the debugging process above.
+
+This is NOT random sabotage. Each mistake is:
+- Common in real engineering (you WILL encounter this in a real job)
+- Fixable with the debugging skills relevant to that phase
+- Followed by a full debugging walkthrough
+
+The user will be told: **"This is a deliberate mistake — let's debug it."**
+
+---
+
+## Planned deliberate mistakes by phase
+
+### Phase 1 — Project Setup
+**Mistake**: Missing `__init__.py` in a package folder.
+**Error**: `ModuleNotFoundError: No module named 'app.routers'`
+**Lesson**: Python package system, what `__init__.py` does
+
+### Phase 1 — First API
+**Mistake**: Forget to include the router in `main.py`.
+**Error**: `GET /health` returns 404 in Swagger even though the route file exists
+**Lesson**: FastAPI router registration, difference between "file exists" and "route is registered"
+
+### Phase 1 — Database
+**Mistake**: Wrong `DATABASE_URL` format (e.g., `sqlite://vault.db` instead of `sqlite:///./vault.db`).
+**Error**: `sqlalchemy.exc.ArgumentError: Could not parse rfc1738 URL from string 'sqlite://vault.db'`
+**Lesson**: Connection strings, how to read SQLAlchemy errors, URL format rules
+
+### Phase 2 — Models
+**Mistake**: Forget to import the model in `models/__init__.py` before calling `create_all()`.
+**Error**: Table doesn't get created, then `OperationalError: no such table: notes` when inserting
+**Lesson**: How SQLAlchemy discovers models, why `create_all` needs to see the model class
+
+### Phase 2 — CRUD
+**Mistake**: Return the SQLAlchemy model object directly from a route (instead of using Pydantic response schema).
+**Error**: `ValueError: sqlalchemy.orm.DeclarativeBase is not a valid pydantic field type`
+**Lesson**: The model/schema separation, why response schemas exist, what Pydantic serialization does
+
+### Phase 3 — Frontend
+**Mistake**: Wrong API URL in `fetch()` (e.g., `/notes` instead of `/api/notes` after the prefix change).
+**Error**: Browser Console shows `404 Not Found` on the fetch call, but the API endpoint exists
+**Lesson**: DevTools Network tab, how to trace a 404 from frontend to backend
+
+### Phase 4 — CORS
+**Mistake**: Add CORS middleware AFTER mounting static files in `main.py`.
+**Error**: CORS headers missing on API responses, error appears in browser Console
+**Lesson**: FastAPI middleware order matters, middleware executes in reverse registration order
+
+### Phase 4 — JWT
+**Mistake**: Forget to set `SECRET_KEY` in `.env` (use empty string).
+**Error**: All tokens validate as valid (empty key = no security) OR all tokens fail depending on the library
+**Lesson**: Why secret key management matters, how to verify a config value is actually loaded
+
+### Phase 6 — Docker
+**Mistake**: Forget `.dockerignore` — copy `.env` into the image.
+**Error**: Not an immediate crash, but show using `docker inspect` that secrets are baked into the image
+**Lesson**: Security-in-containers, why `.dockerignore` is as important as `.gitignore`
+
+### Phase 6 — Docker
+**Mistake**: Use `localhost` in `DATABASE_URL` inside Docker instead of the service name `db`.
+**Error**: `Connection refused` — the app tries to connect to its own container's localhost, not the db container
+**Lesson**: Docker networking, container DNS, why service names are used in connection strings
+
+---
+
+## How to use DevTools for debugging (reference)
+
+When the error is frontend-side, always open DevTools FIRST:
+
+| Symptom | Where to look |
+|---|---|
+| Page loads but data doesn't appear | Network tab → find the failed request |
+| JavaScript error on page | Console tab → read the error message |
+| API call goes out but returns wrong data | Network tab → Response tab of the request |
+| Token not being sent | Network tab → Headers tab → look for Authorization |
+| CORS error | Console tab → red CORS message |
+| App works in Swagger but not in browser | Usually CORS or wrong URL in fetch() |
+
+---
+
+## Debugging commands reference (backend)
+
+```bash
+# See what's running
+ps aux | grep uvicorn
+
+# Check if port is in use
+lsof -i :8000
+
+# Inspect SQLite database directly
+sqlite3 vault.db ".tables"
+sqlite3 vault.db "SELECT * FROM users;"
+
+# Check if env var is loaded
+python -c "from app.config import settings; print(settings.database_url)"
+
+# See Docker container logs
+docker logs <container_name>
+docker logs <container_name> --follow  # live tail
+
+# Check container networking
+docker exec -it <container_name> curl http://db:5432  # test internal DNS
+docker network inspect vault_default  # see all containers on the network
+```
+
+---
+
+## The mindset
+
+A senior engineer does not panic at errors. They:
+1. Read the error
+2. Identify the layer
+3. Form a hypothesis
+4. Test it
+5. Fix and explain
+
+Developing this mental habit is more valuable than knowing any specific technology. Every technology breaks differently, but the debugging process is always the same.