# Repository Analysis

## Executive Summary

The repository is an early skeleton, not an implementation-ready Phase 1 baseline. Product intent is well documented, but current code cannot be treated as a verified foundation: backend imports are inconsistent with file layout, frontend imports missing source files, migration infrastructure is absent despite Alembic being documented, and all API endpoints are placeholders.

Readiness rating: 4/10.

Recommended next move: stabilize the skeleton before implementing feature phases. Do not start meal planning, scraping, email, or shopping-list logic until app startup, build, migrations, and API contract are corrected.

## Current Repo Shape

Implemented or present:
- `docker-compose.yml` with `backend`, `frontend`, `db`, and `nginx` services.
- FastAPI app skeleton under `backend/app`.
- SQLAlchemy model classes colocated in `backend/app/models/__init__.py`.
- Placeholder API routers for profile, recipes, meals, shopping list, pantry, and admin.
- Vite/React/Tailwind frontend skeleton.
- Nginx configs under both `nginx/nginx.conf` and `frontend/nginx.conf`.
- Extensive docs under `docs/` plus `README.md`.

Missing or not present:
- `frontend/index.html`.
- `frontend/package-lock.json`, despite Dockerfile using `npm ci`.
- `frontend/src/pages/Pantry.tsx`, despite being imported by `App.tsx`.
- `backend/alembic.ini` and `backend/alembic/`.
- Backend `schemas/`, `services/`, and `scraper/` directories.
- Tests.
- Authn/authz layer.
- OpenAPI contract beyond FastAPI's generated placeholder routes.

## Blocking Findings

### 1. Backend likely fails during import because model module layout is inconsistent

`backend/app/main.py:4` imports `family_profile`, `ingredient`, `recipe`, `meal_plan`, `home_pantry`, `feedback`, `grocery_item`, `scrape_log`, and `email_log` from `app.models`. Those submodules do not exist. All model classes are currently defined in `backend/app/models/__init__.py`.

Impact: backend startup is likely broken before FastAPI can serve `/health`.

Fix direction:
- Either split models into the imported module files, or remove those submodule imports and import the package/classes consistently.
- Add a backend startup smoke test before continuing any feature work.

### 2. SQLAlchemy relationships contain at least one broken back-populates reference

`backend/app/models/__init__.py:247` sets `RecipeIngredient.recipe = relationship("Recipe", back_populates="recipe_ingredients")`, but `Recipe` does not define `recipe_ingredients`. This is likely to fail mapper configuration once SQLAlchemy evaluates relationships.

Impact: even if import paths are fixed, ORM use can fail at runtime.

Fix direction:
- Add `Recipe.recipe_ingredients` or remove/replace the relationship.
- Decide whether recipe ingredients are normalized via `recipe_ingredient`, stored in `recipe.ingredients` JSONB, or intentionally duplicated with clear ownership.

### 3. Frontend build is blocked by a missing imported page

`frontend/src/App.tsx:5` imports `./pages/Pantry`, and `frontend/src/App.tsx:32` routes `/pantry` to it. No `frontend/src/pages/Pantry.tsx` file exists.

Impact: TypeScript/Vite build should fail immediately.

Fix direction:
- Add a minimal `Pantry.tsx` placeholder, or remove the route/import until the page exists.

### 4. Frontend Docker build is blocked by missing npm lockfile

`frontend/Dockerfile:5-6` copies `package*.json` then runs `npm ci`. There is no `frontend/package-lock.json`.

Impact: `npm ci` fails without a lockfile, so the frontend container cannot build reproducibly.

Fix direction:
- Generate and commit `package-lock.json`, or change Dockerfile to use `npm install` for the skeleton phase. Prefer lockfile.

### 5. Vite app is missing required HTML entrypoint

No `frontend/index.html` exists. Vite expects an HTML entrypoint at project root unless customized.

Impact: local dev/build is blocked even after fixing `Pantry.tsx`.

Fix direction:
- Add standard Vite `index.html` pointing to `/src/main.tsx`.

### 6. Alembic is documented and installed but not configured

`backend/requirements.txt:4` includes Alembic and docs repeatedly call `alembic upgrade head`, but no `backend/alembic.ini` or `backend/alembic/` exists. Meanwhile `backend/app/main.py:17` calls `Base.metadata.create_all(bind=engine)` at import/startup.

Impact: schema ownership is confused. Runtime table creation can mask missing migrations and produce unmanaged dev DB state.

Fix direction:
- Create Alembic config and first migration.
- Remove `create_all` from normal app startup once migrations exist.
- Add a documented migration verification path.

## Important Findings

### 7. API routes are placeholders with no schemas or persistence

All API functions currently return static `{"message": ...}` payloads. Examples: `backend/app/api/profile.py:8-15`, `backend/app/api/recipes.py:8-20`, `backend/app/api/meals.py:8-20`, and `backend/app/api/admin.py:8-20`.

Impact: the route shape exists, but no request models, response models, validation, DB reads/writes, or errors exist. Treat these as route stubs, not usable endpoints.

Fix direction:
- Add Pydantic schemas before endpoint implementation.
- Implement one resource end-to-end first, probably profile or ingredients, to establish patterns.

### 8. Admin endpoints are unauthenticated

`backend/app/api/admin.py` exposes scrape trigger, logs, and test email routes without auth. Docs anticipate remote access via reverse proxy.

Impact: once implemented, these routes could trigger external scraping, send email, and expose operational logs.

Fix direction:
- Define auth before implementing admin behavior.
- At minimum, gate admin routes behind a dependency and environment-configured secret/session/proxy auth.

### 9. Email approval security is not implemented and not modeled yet

Models include `approval_token` and `approval_token_expires` in `MealPlanItem`, but no token route, validation, hashing, single-use behavior, or audit trail exists. Current routes approve/deny by meal ID, not token.

Impact: approval workflow cannot safely be exposed via email links.

Fix direction:
- Decide token route contract before frontend/email work.
- Use high-entropy signed or stored tokens with expiry and replay handling.
- Keep meal-ID approval routes authenticated if they remain.

### 10. `SECRET_KEY` has an unsafe default

`backend/app/config.py:13` sets `SECRET_KEY: str = "dev-secret-key"`. `.env.example` says to change it, but code does not enforce change outside dev.

Impact: future signed tokens/sessions could be deployed with a known secret.

Fix direction:
- Make `SECRET_KEY` required for non-development environments.
- Document environment mode and startup validation.

### 11. SQLAlchemy 2 health query may fail

`backend/app/main.py:28` calls `db.execute("SELECT 1")`. With SQLAlchemy 2, textual SQL should use `text("SELECT 1")`.

Impact: `/health/db` can report failure even when DB is reachable.

Fix direction:
- Use `from sqlalchemy import text` and `db.execute(text("SELECT 1"))`.

### 12. Docker Compose exposes backend and frontend directly plus nginx

`docker-compose.yml` maps backend `8000:8000`, frontend `3000:80`, and nginx `80:80`/`443:443`. This is convenient for dev but contradicts a production reverse-proxy boundary if deployed unchanged.

Impact: backend bypasses nginx controls such as future rate limiting/auth headers unless ports are removed or bound to localhost.

Fix direction:
- Split dev and prod compose files.
- In prod, expose only reverse proxy and keep backend/frontend on internal network.

### 13. Nginx SSL and rate limiting are not implemented

`nginx/nginx.conf` and `frontend/nginx.conf` only provide SPA fallback and `/api/` proxying over HTTP. No TLS cert mounts, rate limits, security headers, request size limits, or proxy timeout policy exist.

Impact: deployment docs overstate production readiness.

Fix direction:
- Keep current nginx config labeled as local/dev only.
- Add production config later with TLS, headers, and route-specific limits.

## Maintainability Findings

### 14. Model file is too large for early iteration and hides domain decisions

`backend/app/models/__init__.py` contains all models and several unresolved design choices. This makes migrations, ownership, and imports harder to reason about.

Recommendation:
- Split per aggregate/table after schema ownership is decided, or keep colocated temporarily but remove false submodule imports.
- Add tests that import and configure all mappers.

### 15. Schema constraints are only partially represented

Some documented constraints are in code, such as `day_of_week BETWEEN 0 AND 6` and feedback rating range. Others are missing or underspecified, such as family counts, valid status enums, meal type values, and never-suggest rules.

Recommendation:
- Prefer Python enums plus DB checks for status/meal type/reason fields.
- Add validation at Pydantic layer before DB writes.

### 16. API prefix behavior may produce trailing-slash-only endpoints

Routers are included with prefixes like `/api/profile`, and router paths use `/`. This exposes `/api/profile/` rather than `/api/profile` unless FastAPI redirects. Docs mostly specify no trailing slash.

Recommendation:
- Decide canonical trailing-slash style and update routes/docs together.

### 17. No repository-level quality gates exist

There are no tests, no backend lint/format config, no frontend lockfile, and no CI config. Docs mention pytest, Black, isort, ESLint, and Prettier, but config and scripts are incomplete.

Recommendation:
- Add minimal smoke tests first: backend import/app creation, mapper configuration, frontend build.
- Add formatting/lint configs only when used by scripts/CI.

## Documentation Alignment

The separate documentation review in `Review/docs-gpt5.5.md` covers doc-specific contradictions. Repo analysis confirms several documentation risks against current files:

- Phase status is overstated: skeleton is present but not verified.
- Alembic workflow is documented but absent.
- API route contract differs between docs and code.
- Production deployment docs exceed current compose/nginx capability.
- Model/schema docs do not resolve JSONB ingredients vs normalized ingredients.

## Recommended Remediation Order

### Phase 0: Make skeleton start and build

- Fix backend model imports.
- Fix SQLAlchemy `recipe_ingredients` relationship mismatch.
- Fix `/health/db` SQLAlchemy 2 textual SQL.
- Add `frontend/index.html`.
- Add or remove `Pantry.tsx` route.
- Add frontend lockfile or adjust Dockerfile.
- Run backend import smoke test and frontend build.

### Phase 1: Establish schema/migration baseline

- Decide ingredient representation.
- Configure Alembic.
- Generate initial migration.
- Remove runtime `create_all` from normal startup.
- Add seed-data strategy.

### Phase 2: Establish API and security baseline

- Define canonical OpenAPI contract.
- Add Pydantic schemas.
- Add auth dependency for admin and authenticated web routes.
- Define approval-token routes and behavior.
- Add CORS/trusted-host/proxy assumptions.

### Phase 3: Implement first vertical slice

- Implement profile or ingredient CRUD end-to-end.
- Add DB-backed tests.
- Wire frontend API client for one real endpoint.
- Use this slice as pattern for recipes, pantry, and meal plans.

## Verification Matrix To Add

Minimum commands expected before declaring foundation complete:

```bash
docker compose config
docker compose build backend
docker compose build frontend
docker compose up -d db
docker compose run --rm backend python -c "from app.main import app; print(app.title)"
docker compose run --rm backend alembic upgrade head
docker compose run --rm backend pytest
docker compose run --rm frontend npm run build
```

These commands may not pass today; they are the gate that should define “Phase 1 complete”.

## Final Assessment

The repo is valuable as a product specification plus rough skeleton. It should not be considered a working app foundation yet. Biggest immediate risk is building new features on top of a skeleton that likely does not start or build. Stabilize imports, frontend entrypoints, Docker builds, and migrations first; then implement one small DB-backed vertical slice before expanding into scraper/email/planner complexity.