ROADMAP.md

@@ -0,0 +1,122 @@
+# SPARC Roadmap
+
+Semiconductor Patent & Analytics Report Core -- development priorities.
+
+## Current State
+
+SPARC is a patent analysis platform with a working end-to-end pipeline:
+Python/FastAPI backend, React/TypeScript frontend, PostgreSQL for persistence
+and caching, Docker Compose for local development, and Gitea Actions CI/CD for
+image builds. Core features (patent retrieval via SerpAPI, PDF parsing, LLM
+analysis via OpenRouter/Claude, batch processing, JWT authentication, analytics
+dashboard) are all implemented and functional.
+
+---
+
+## P1 -- High Priority
+
+These items address correctness, security, and reliability gaps that should be
+resolved before broader production use.
+
+### Security hardening
+
+- **Rotate default JWT secret.** `auth.py` ships a fallback
+  `sparc-secret-key-change-in-production` that will be used if `JWT_SECRET` is
+  unset. Add a startup check that refuses to start with the default secret in
+  non-development environments.
+- **CORS allow-origins are hardcoded.** `api.py` only permits
+  `localhost:3000` and `localhost:5173`. Make the allowed origins configurable
+  via environment variable so the dashboard works when deployed behind a real
+  domain.
+- **Database credentials in docker-compose.yml.** The compose file embeds
+  `postgres:postgres` in plain text. Reference a `.env` file or Docker secrets
+  instead.
+
+### Error handling and resilience
+
+- **`get_db_client()` in `auth.py` creates a new `DatabaseClient` on every
+  call.** This bypasses the connection pool and can exhaust database
+  connections under load. Refactor to share a single pooled client.
+- **`_jobs` dict is in-memory only.** Job state is lost on API restart. Persist
+  job status in PostgreSQL or Redis so async batch results survive restarts.
+- **No rate limiting on auth endpoints.** `/auth/login` and `/auth/register`
+  are unprotected against brute-force or abuse. Add rate limiting middleware.
+
+### Test coverage for auth and admin
+
+- The existing API tests (`tests/test_api.py`) bypass authentication entirely.
+  Add tests that exercise the JWT flow: registration, login, protected-route
+  access, token refresh, and admin-only endpoints.
+
+---
+
+## P2 -- Medium Priority
+
+Improvements to usability, performance, and developer experience.
+
+### Backend
+
+- **Add structured logging.** Replace `print()` calls throughout `analyzer.py`,
+  `serp_api.py`, and `llm.py` with Python `logging` so log levels and
+  formatting are consistent.
+- **Make LLM model configurable.** `llm.py` hardcodes
+  `anthropic/claude-3.5-sonnet`. Accept a `MODEL` environment variable to allow
+  switching models without code changes.
+- **SERP cache TTL is hardcoded to 24 hours.** Expose `SERP_CACHE_TTL_HOURS`
+  as an environment variable in `config.py`.
+- **Patent PDF storage.** PDFs are saved to a local `patents/` directory. For
+  containerized deployments, consider object storage (S3/MinIO) or at minimum
+  document the volume mount requirement more prominently.
+- **`analyze_single_patent` assumes local file path.** The method constructs
+  `patents/{patent_id}.pdf` and reads from disk, but does not download the PDF
+  first. Either integrate the download step or document the prerequisite.
+- **`Patent.patent_id` typed as `int` in `types.py` but used as `str`
+  everywhere.** Fix the type annotation to `str`.
+
+### Frontend
+
+- **No loading/error states on several pages.** The Batch and Analytics pages
+  would benefit from skeleton loaders and user-friendly error messages.
+- **No dark mode.** Tailwind is configured but no dark variant is applied.
+- **Missing `package-lock.json` or `pnpm-lock.yaml`.** The frontend has no
+  lockfile committed, leading to non-reproducible builds.
+
+### CI/CD
+
+- **No test stage in the Gitea Actions workflow.** `build.yaml` builds and
+  pushes images but never runs `pytest`. Add a test job that gates the build.
+- **No linting or type checking.** Add `ruff` (Python) and `tsc --noEmit`
+  (TypeScript) to CI.
+
+---
+
+## P3 -- Nice to Have
+
+Lower-urgency enhancements and future features.
+
+- **Export analysis reports.** Allow users to download analysis results as PDF
+  or CSV from the dashboard.
+- **Comparison view.** Side-by-side comparison of two companies' patent
+  portfolios.
+- **Scheduled/recurring analysis.** Periodically re-analyze tracked companies
+  and alert on significant changes.
+- **Webhook/notification support.** Send alerts (Slack, Discord, email) when
+  batch jobs complete or when a company's innovation score changes
+  significantly.
+- **Multi-model support.** Let users choose between LLM providers per analysis
+  (e.g., GPT-4o, Gemini, Claude) and compare outputs.
+- **Patent trend charts.** Visualize patent filing frequency and technology
+  category distribution over time in the Analytics page.
+- **API pagination.** The `/analyze/batch` and `/jobs` endpoints could benefit
+  from cursor-based pagination for large result sets.
+- **OpenAPI client generation.** Auto-generate the TypeScript API client from
+  the FastAPI OpenAPI spec to keep frontend types in sync.
+
+---
+
+## Infrastructure and Deployment
+
+Kubernetes manifests, Helm charts, and cluster-level concerns (MetalLB,
+storage, FluxCD sync) are tracked in the
+[Talos](https://10.0.1.10/leeworks-agents/Talos) repository. File
+infrastructure-related issues there, not here.