Service Architecture - honeypot
This document describes the implemented prototype and the controls required before it can become a deployable service.
Technical Role
- Lane: Repository-specific proof surface and implementation reference
- Primary reader: Technical reviewers, operators, maintainers, and partners
- First motion: Validate the synthetic demo, fail-closed security tests, and handover workflow before designing a customer-specific production architecture.
Recommended Architecture
~~~text Reviewer with synthetic data -> static proof surface -> local React client -> FastAPI prototype -> demo-local users and self-issued JWT role claims -> process-local refresh, CSRF, rate-limit, task, and demo index state -> optional Azure document/search/model adapters in APP_MODE=live -> human-reviewed handover draft ~~~
APP_MODE=live means cloud adapters are connected. It does not mean the security or tenancy layer is production-ready.
Resource Plan
| Resource | Use | Enable timing |
|---|---|---|
| Static hosting | Public, cacheable proof surface and documentation. | Keep as the default until server-side state is required. |
| App/API runtime | Local or isolated integration-evaluation runtime. | Do not expose to untrusted users with the current security profile. |
| Identity provider | OIDC/SSO verification, tenant membership, server-authoritative roles, and access reviews. | Required before staging or production can start. |
| Shared security state | Refresh-token revocation, CSRF/session state, and distributed rate limits. | Required before multiple replicas or production traffic. |
| Data layer | Tenant-scoped workflow state, audit history, retention, and deletion records. | Required before customer data is accepted. |
| Object storage | Uploads, reports, screenshots, model artifacts, or signed exports. | Enable only when persistent artifacts are required. |
| Queue/cache | Async jobs, retries, scheduled checks, and rate-limited workflows. | Enable when reliability needs exceed direct request handling. |
| Observability | Error tracking, performance traces, and privacy-safe usage signals. | Enable before external users test the workflow. |
Repo-Specific Resources
- Public demo or static proof route
- CI or local quality gate
- Architecture blueprint validation
- Fail-closed startup validation in
app/security.py - Local-only demo auth and process-local security stores
- Secret manager for cloud integration credentials
- Privacy-safe telemetry only when needed
Security Promotion Gate
The repository deliberately implements no bypass flag for production. staging and production fail startup while the following are absent:
- External identity verification with issuer, audience, algorithm, and key-rotation validation.
- Server-authoritative tenant membership and role lookup; token role strings alone are insufficient.
- Shared refresh revocation, CSRF/session, and rate-limit state.
- Document-level authorization at both ingestion and retrieval.
- Tenant-scoped persistence, audit events, retention, deletion, backup, and restore.
- Production CORS/proxy trust configuration, observability, incident response, and rollback validation.
Changing JWT_SECRET, overriding demo passwords, or connecting Azure services cannot satisfy this gate.
Information Needed From Account Owner
- Hosting account and deployment target
- Domain or DNS access when a custom domain is required
- Runtime secret names and ownership
- Data retention and deletion policy
- Observability project and alert routing
Prototype Review Checklist
- Public demo route or README proof link is current.
- Service boundary states what the system does and does not do.
- Only synthetic or explicitly approved non-sensitive data is used.
- Production fail-closed tests remain green.
- Data storage, retention, and deletion paths are designed before private data is accepted.
- Secrets are stored in platform secret managers, never committed to the repo.
- Usage alerts or manual approval gates are enabled before external testing.
- Logs and analytics avoid private payloads.
- Rollback or disable path exists for every external integration.
- No artifact calls the current demo JWT/CSRF/RBAC path production-ready.