feat(scaffold): add ZyntroAI merged monorepo scaffold (additive)

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.gitignore
+**/node_modules
+**/.venv
+**/__pycache__
+**/.pytest_cache
+logs
+.env
+**/*.log
+**/dist

.github/PULL_REQUEST_TEMPLATE/bugfix.md

@@ -0,0 +1,36 @@
+---
+name: 🐛 Bugfix
+about: Defect fix with reproduction
+title: "fix: "
+---
+
+## 🐛 Bugfix
+
+### Bug description
+What is the bug, and how was it observed?
+
+### Reproduction
+Steps to reproduce:
+1. _____
+
+### Root cause
+What was the underlying cause? (be specific)
+
+### Fix
+- [ ] Root-cause fix applied (not a symptom patch)
+- [ ] Minimal, targeted diff
+
+### Tests
+- [ ] Regression test added for this bug
+- [ ] Existing tests pass
+
+### Test evidence
+```
+(before/after output)
+```
+
+### Checklist
+- [ ] Bug reproduced before fix
+- [ ] Root cause identified
+- [ ] Regression test included
+- [ ] No unintended behavior change

.github/PULL_REQUEST_TEMPLATE/dependencies.md

@@ -0,0 +1,37 @@
+---
+name: 📦 Dependency
+about: Package bump, upgrade, CVE remediation
+title: "build(deps): "
+---
+
+## 📦 Dependencies
+
+### Change
+Which dependency and version change? (e.g. `package@1.2.3` → `@2.0.0`)
+
+### Reason
+- [ ] Routine update
+- [ ] Security / CVE remediation (reference CVE)
+- [ ] Feature needed upstream
+
+### Compatibility
+- [ ] Semver-compatible (patch/minor)
+- [ ] Major version — breaking changes reviewed
+- [ ] Transitive deps reviewed
+
+### Validation
+- [ ] Dependency review passed (CI)
+- [ ] Tests pass with new version
+- [ ] No known CVEs remain in the bump
+- [ ] Lockfile / manifest updated together
+
+### Test evidence
+```
+(paste test / audit output)
+```
+
+### Checklist
+- [ ] Version pinned appropriately (not floating)
+- [ ] Both manifest + lockfile updated
+- [ ] CI green
+- [ ] Change is isolated to the dependency

.github/PULL_REQUEST_TEMPLATE/docs.md

@@ -0,0 +1,32 @@
+---
+name: 📚 Documentation
+about: README, API docs, Obsidian vault, guides
+title: "docs: "
+---
+
+## 📚 Docs
+
+### What is documented
+Describe the documentation change and where it lives.
+
+### Type
+- [ ] README / repo docs
+- [ ] API / reference docs
+- [ ] Obsidian vault / knowledge base
+- [ ] Runbook / SOP
+- [ ] Tutorial / guide
+
+### Scope
+- [ ] New section/file
+- [ ] Correction / clarification
+- [ ] Removal of stale content
+
+### Index impact
+- [ ] Knowledge index (Algolia/Obsidian) needs re-sync
+- [ ] Links verified (no broken anchors)
+
+### Checklist
+- [ ] Content is accurate (no invented claims)
+- [ ] Code samples are correct / runnable
+- [ ] Terminology consistent with repo
+- [ ] No secrets or internal details leaked

.github/PULL_REQUEST_TEMPLATE/infra-config.md

@@ -0,0 +1,39 @@
+---
+name: ⚙️ Configuration
+about: Env, Docker, K8s, CI, infra-as-code
+title: "config: "
+---
+
+## ⚙️ Infra/Config
+
+### What is being changed
+Describe the infra/config change (env, Docker, K8s, CI, IaC).
+
+### Scope
+- [ ] Environment / secrets config
+- [ ] Docker / docker-compose
+- [ ] Kubernetes manifests
+- [ ] CI/CD workflows
+- [ ] Observability / monitoring
+- [ ] Other: _____
+
+### Impact
+- [ ] Existing behavior preserved (additive)
+- [ ] Services affected: _____
+
+### Validation
+- [ ] YAML validated
+- [ ] Config values correct (no secrets committed)
+- [ ] Local parity confirmed (docker compose up)
+- [ ] Rollback path defined
+
+### Test evidence
+```
+(paste validation output)
+```
+
+### Checklist
+- [ ] Change is minimal and targeted
+- [ ] No secrets committed
+- [ ] Documented in README / runbook where needed
+- [ ] Rollback documented

.github/PULL_REQUEST_TEMPLATE/release.md

@@ -0,0 +1,34 @@
+---
+name: 📦 Release
+about: Version bump, changelog, deployment cut
+title: "release: "
+---
+
+## 📦 Release
+
+### Version
+`v0.0.0` → `v0.0.0` (specify)
+
+### Changelog entry
+Summarize the user-facing changes in this release.
+
+### Deployment plan
+- [ ] Migrations included / none
+- [ ] Feature flags / rollback strategy defined
+- [ ] Environment variables documented
+- [ ] Backwards-compatible
+
+### Pre-flight checks
+- [ ] Tests pass on CI
+- [ ] Changelog updated
+- [ ] Tag created / version bumped in manifest
+- [ ] Release notes drafted
+
+### Rollback
+What is the rollback path if this release is reverted?
+
+### Checklist
+- [ ] Version bumped in all manifests
+- [ ] Changelog reflects this release
+- [ ] Deployment steps documented
+- [ ] Rollback plan confirmed

.github/PULL_REQUEST_TEMPLATE/security.md

@@ -0,0 +1,41 @@
+---
+name: 🔒 Security
+about: Vulnerability, auth, secrets, or security hardening
+title: "security: "
+---
+
+## 🔒 Security
+
+### Vulnerability / Issue
+What is the security issue being addressed? (CVE, weakness, or risk)
+
+### Affected area
+- [ ] Authentication / Authorization
+- [ ] Secrets / credentials handling
+- [ ] Input validation / injection
+- [ ] Data protection (encryption at rest / in transit)
+- [ ] Dependency / supply-chain
+- [ ] Other: _____
+
+### Root cause
+Describe the root cause and how it was identified.
+
+### Fix
+- [ ] Code change applied
+- [ ] No secrets committed (scanned)
+- [ ] Existing tests updated / new tests added
+- [ ] Verified exploit no longer succeeds
+
+### Impact
+What is the blast radius if this is not fixed?
+
+### Test evidence
+```
+(paste test output / proof the fix works)
+```
+
+### Checklist
+- [ ] Security issue verified
+- [ ] Change is minimal and targeted
+- [ ] No plaintext secrets introduced
+- [ ] Reviewer security-checks the diff

FILE-MANIFEST.md

@@ -0,0 +1,34 @@
+# ZyntroAI Scaffold — File Manifest
+
+All files listed here are NEW additions (no-clobber). Nothing existing on main was modified or deleted.
+
+## Added files (17 total)
+
+### (root)
+- `.dockerignore`
+- `FILE-MANIFEST.md`
+- `ZYNTROAI-SCAFFOLD.md`
+
+### .github
+- `.github/workflows/pr-ci.yml`
+- `.github/workflows/pr-validation.yml`
+
+### backend
+- `backend/Dockerfile`
+- `backend/alembic.ini`
+- `backend/alembic/`
+- `backend/app/`
+- `backend/pyproject.toml`
+- `backend/tests/`
+
+### frontend
+- `frontend/`
+
+### k8s
+- `k8s/backend-deployment.yaml`
+- `k8s/backend-hpa.yaml`
+- `k8s/frontend-deployment.yaml`
+- `k8s/secrets.yaml`
+
+### knowledge
+- `knowledge/`

ZYNTROAI-SCAFFOLD.md

@@ -0,0 +1,63 @@
+# ZyntroAI — Merged Monorepo Scaffold (Proposal)
+
+> **Status: PROPOSAL / PR for review** — additive, no-clobber addition to the
+> repo. Does not replace or modify any existing file. See `FILE-MANIFEST.md`
+> for the full inventory and the colliding-names list.
+
+Unified architecture across backend, frontend, knowledge indexing, Kubernetes
+and CI/CD — presented as a ready-to-review scaffold so nothing existing is
+overwritten before you decide what to adopt.
+
+Generated: 2026-09-09 · Python 3.11 · FastAPI · React · PostgreSQL · Redis · K8s · GitHub Actions
+
+## What this PR adds
+
+| Area | Path | Contents |
+|---|---|---|
+| Backend (Python) | `backend/` | FastAPI + SQLModel async API, Alembic migrations, Pydantic config, JWT auth, pytest suite (6 passing) |
+| Frontend | `frontend/` | React + Vite + TypeScript shell with type-safe API client |
+| Knowledge | `knowledge/` | Obsidian REST API client + Algolia indexer (`diff_policy.py`, `push_index.py`) |
+| Kubernetes | `k8s/` | Backend/frontend Deployments, Services, Ingress, HPA, Secrets (helm chart untouched) |
+| CI/CD | `.github/workflows/` | `pr-ci.yml` (type classify → reusable validation → tests) + `pr-validation.yml` |
+| Docs | `README.md`, `FILE-MANIFEST.md` | This spec + machine-readable inventory |
+
+> **Note:** `docker-compose.yml` and `.env.example` already existed on `main`;
+> this PR intentionally does **not** overwrite them (see
+> `FILE-MANIFEST.md` → "Collisions — left untouched").
+
+## Backend core
+
+`backend/app/core/config.py` — type-safe env via pydantic-settings.
+`backend/app/core/security.py` — bcrypt hashing + JWT (python-jose).
+`backend/app/infrastructure/db.py` — async SQLModel engine + sessions.
+`backend/app/api/deps.py` — `get_db` + JWT `get_current_user`.
+`backend/app/main.py` — lifespan, CORS, exception handler, `/health`.
+`backend/app/api/v1/...` — `models/item.py`, `schemas/item.py`,
+`services/item_service.py`, `routes/items.py` (full CRUD data path).
+
+### Verify
+
+```bash
+cd backend
+pip install -e ".[dev]"     # or: pip install fastapi sqlmodel ... pytest
+pytest tests/ -v            # 6 passing
+```
+
+## CI/CD workflow
+
+- `.github/workflows/pr-ci.yml` — `pull_request` + `push` to `main`; classifies
+  the PR type from its body, calls the reusable validator, runs backend lint +
+  tests, and syncs the knowledge index on Docs PRs / `main`.
+- `.github/workflows/pr-validation.yml` — reusable `workflow_call`: title
+  format (Conventional Commits), template completeness, checklist scan, secrets
+  scan (Gitleaks), Ruff, TS build, and type-gated dependency/markdown/release
+  checks. Emits a `validation_result` output for branch protection.
+
+## Next steps
+
+1. Review this PR's additions (everything is **new**; nothing existing changed).
+2. Decide which areas to adopt (e.g. keep the new `backend/` Python app
+   separate from the existing root `app/`, or reconcile them).
+3. Set branch protection to require `validate / validation_result` + 1 approval.
+4. Add secrets: `ALGOLIA_APP_ID`, `ALGOLIA_API_KEY`, `OBSIDIAN_API_TOKEN`,
+   `GITHUB_TOKEN`.

backend/Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+
+# Build deps for psycopg/asyncpg wheels are only needed at install time.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends gcc build-essential curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml .
+RUN pip install --no-cache-dir --prefix=/install .
+
+FROM python:3.11-slim
+
+WORKDIR /app
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PYTHONPATH=/app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /install /usr/local
+COPY app/ /app/app/
+COPY alembic.ini /app/alembic.ini
+COPY alembic/ /app/alembic/
+
+RUN useradd --create-home --uid 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]