diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..42b571a --- /dev/null +++ b/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.