API system diagram · confidential working draft

Source delivery, citizen control, office review.

The intended product boundary: a source never receives a citizen’s open vault; an office never receives a document until the citizen grants the exact, limited permission.

Role 01 · document provider

Source workspace

One company-specific credential and one permitted document category per delivery.

  • OAuth client credentials in production
  • Scope + tax year validation
  • Short-lived upload authorization
  • Signed delivery receipt
CivicTax Cloud

Private citizen vault

Private storage, organization, notification events, and a complete record of document activity.

  • Tenant isolation
  • Private encrypted object storage
  • Classification proposes; review required
  • Audit event for every action
Role 03 · tax office

Office review queue

The office receives only the authorized package and retains its own brand, portal, and client relationship.

  • Role-based user access
  • Case checklist and status
  • Webhook delivery events
  • Human review before tax action
Identity boundary

Production identity connections require official provider approval and registered redirect/security controls. They are not assumed by the MVP.

Security boundary

Private buckets, KMS encryption, Secrets Manager, token expiry, rate limits, logging safeguards, and multi-tenant authorization belong in the production AWS environment.

Connector boundary

Tax software connectors stay mock/placeholder until the vendor provides official APIs, credentials, documentation, and contractual permission.

Production architecture target

AWS-ready deployment boundary

Edge & application

HTTPS-only public entry points for office servers, sources, and citizen sessions.

  • API Gateway
  • WAF and rate limiting
  • ECS/Fargate or Lambda
  • OAuth2/OIDC token services

Data & documents

Separate operational data from private document objects and never expose permanent document links.

  • PostgreSQL / RDS
  • Private S3 buckets
  • KMS encryption keys
  • Short-lived signed URLs

Operations & assurance

Visibility and response are part of the service, not an afterthought.

  • Secrets Manager
  • CloudWatch and CloudTrail
  • Backups and retention controls
  • Incident response and access reviews