When a Java microservice needs file handling, state, config, or secret logic,
the team should not reinvent the mental model from scratch.

Do not store user file directly in accepted state.
Do not use client filename as storage path.
Do not expose bucket/key as domain identity.
Do not skip metadata-payload consistency checks.

Large or untrusted files:
upload session -> presigned upload -> quarantine -> scan -> accepted/rejected

No correctness-critical state only in local disk, heap, or pod memory.
No shared database mutation across service ownership boundaries.
No cache as hidden source of truth.

Config must have owner, schema, validation, provenance, and safe default.
Feature flags must have owner and expiry.
Secrets must never be stored in ConfigMap/plain config.

Secret delivery is not secret rotation.
Secret update is not consumer adoption.
Old credential revoke is final step.

# ADR: File Handling Architecture for <Service>

## Status
Proposed | Accepted | Deprecated

## Context
- What files are handled?
- Who uploads/generates them?
- Data classification:
- Size range:
- Retention/compliance requirements:
- Access model:
- Expected volume:

## Decision
- Upload model:
- Storage:
- Metadata source of truth:
- Lifecycle states:
- Scan/validation:
- Download model:
- Retention/legal hold:
- Audit events:
- Reconciliation:

## Alternatives Considered
1. Proxy upload
2. Direct upload
3. DB BLOB
4. Shared filesystem
5. External DMS

## Consequences
### Positive
- ...

### Negative
- ...

## Invariants
- ...

## Failure Handling
- ...

## Observability
- ...

## Security
- ...

## Rollback/Migration
- ...

# ADR: Configuration Delivery for <Service>

## Context
- Config categories:
- Environments:
- Reload requirements:
- Security/compliance impact:
- Existing platform constraints:

## Decision
- Source of truth:
- Delivery mechanism:
- Schema:
- Validation:
- Promotion:
- Runtime reload:
- Drift detection:
- Rollback:

## Reload Classification
| Key/Group | Reloadable | Owner | Risk |
|---|---|---|---|

## Invariants
- ...

## Operational Model
- ...

## Alternatives
- Spring Cloud Config
- Kubernetes ConfigMap
- GitOps rendered config
- Feature flag platform
- Database-backed config

## Consequences
- ...

# ADR: Secret Management for <Service>

## Context
- Secret list:
- Consumers:
- Dependency:
- Rotation requirement:
- Availability impact:
- Compliance/security requirement:

## Decision
- Secret authority:
- Delivery:
- Runtime consumption:
- Rotation strategy:
- Reload/rollout:
- Least privilege:
- Audit:
- Emergency rotation:

## Secret Inventory
| Secret | Source | Consumer | Rotation | Reload |
|---|---|---|---|---|

## Invariants
- Secret not logged
- Consumer refresh defined
- Old credential not revoked before proof
- ...

## Failure Handling
- Secret source down:
- Bad new credential:
- Expired secret:
- Rollback:

## Observability
- ...

# Runbook: <Problem>

## Symptoms
- Alerts:
- User-visible impact:
- Metrics:
- Logs:

## Severity
- Sev:
- Escalation:

## Immediate Checks
1. ...
2. ...
3. ...

## Diagnosis
- Query/dashboard:
- Expected normal:
- Abnormal patterns:

## Mitigation
- Safe action:
- Risk:
- Approval required:

## Recovery
- Steps:
- Validation:
- Rollback:

## Evidence to Capture
- Audit events:
- Logs:
- Metrics:
- Config/secret versions:
- Timeline:

## Post-Incident
- Root cause:
- Corrective actions:
- Tests to add:
- Runbook updates:

metadata_payload_mismatch_total > 0
download returns 404 from object storage
accepted file missing object

1. Identify fileId.
2. Load metadata row.
3. Check lifecycle status.
4. Check object bucket/key/version.
5. Query object storage HEAD.
6. Check audit events around upload/acceptance.
7. Check recent storage/delete events.
8. Check reconciliation reports.

dependency_auth_failure_total spike
secret_rotation_failed_total
pods mixed secret versions
secret_seconds_until_expiry low

1. Do not revoke old credential.
2. Pause rollout.
3. Identify new version and affected consumers.
4. Check canary readiness.
5. Check dependency auth logs.
6. Confirm old credential still valid.

all consumers healthy
new version used
old usage zero for observation window
old revoked
audit event recorded

config_drift_detected_total
live ConfigMap differs from Git
pods report unknown config version
behavior changed without deployment

1. Compare desired Git version vs live ConfigMap.
2. Check Kubernetes audit for update actor.
3. Check GitOps controller events.
4. Check app effective config version endpoint.
5. Identify high-risk keys changed.
6. Check correlated incidents after drift timestamp.

- If unsafe: revert immediately to Git desired or previous safe version.
- If emergency valid: record exception and backfill Git.
- Restrict actor/RBAC if unauthorized.
- Add policy to prevent recurrence.

audit_outbox_oldest_age_seconds > threshold
audit_publish_failure_total increasing
audit sink unavailable

1. Check audit sink health.
2. Check outbox table growth.
3. Check publisher logs.
4. Check duplicate/idempotency errors.
5. Check network/credential issues.

- Restart/fix publisher.
- Scale publisher if throughput issue.
- Pause high-risk operations if policy requires.
- Do not delete outbox rows manually.
- Replay idempotently.

oldest age decreasing
publish success increasing
no gaps in event IDs
audit sink confirms receipt

[ ] Artifact classified
[ ] Owner defined
[ ] Source of truth defined
[ ] Lifecycle state machine defined
[ ] Invariants defined
[ ] Threat model completed
[ ] Access model defined
[ ] Config/secret classification done
[ ] Failure modes listed
[ ] Observability plan defined
[ ] Audit events defined
[ ] Reconciliation plan defined
[ ] ADR written

[ ] No `MultipartFile.getBytes()` for large/unbounded file
[ ] No client filename used as path
[ ] No bucket/key exposed as public domain ID
[ ] No raw secret in logs/exceptions
[ ] No request/response body logging by default
[ ] Typed config uses validation
[ ] Invalid lifecycle transition impossible
[ ] Idempotency implemented for retryable commands
[ ] External side effects have compensation/reconciliation
[ ] Metrics labels bounded and non-sensitive
[ ] Audit events emitted for material decisions

[ ] File upload allowlist/size/content validation
[ ] Quarantine before trust
[ ] Malware scan decision model
[ ] Payload access authorization separate from metadata
[ ] Presigned URL TTL and logging policy
[ ] Least privilege IAM/RBAC
[ ] Kubernetes Secret access restricted
[ ] Secret rotation strategy documented
[ ] Config cannot disable security controls in prod
[ ] Actuator/debug endpoints restricted
[ ] Logs/traces/metrics redacted
[ ] Audit store protected

[ ] Readiness checks required dependencies
[ ] Liveness not tied to transient dependency failure
[ ] Dashboards exist
[ ] Alerts have runbooks
[ ] Reconciliation jobs deployed
[ ] DLQ monitored
[ ] Storage lifecycle/incomplete multipart cleanup configured
[ ] Secret version/expiry observable
[ ] Config version observable
[ ] Audit outbox monitored
[ ] Rollback tested
[ ] Chaos/failure scenario tested in staging
[ ] Incident owner defined

- all buckets/prefixes
- DB metadata tables
- file types
- object keys with PII
- configs and sources
- secrets and consumers
- access policies
- retention rules
- audit gaps

- stop direct bucket access where possible
- add metadata-payload reconciliation
- add audit events for critical operations
- add config schema validation
- add secret scanning
- add least privilege

- introduce stable fileId
- backfill checksums
- backfill object metadata/tags
- map lifecycle states
- move secrets to manager
- move config to governed path
- add runbooks and alerts

- compare counts
- verify checksums
- test downloads
- test retention
- test secret rotation
- test rollback

public final class FileLifecycleGuard {
    private static final Map<FileStatus, Set<FileStatus>> ALLOWED = Map.of(
        FileStatus.UPLOADING, Set.of(FileStatus.UPLOADED),
        FileStatus.UPLOADED, Set.of(FileStatus.QUARANTINED),
        FileStatus.QUARANTINED, Set.of(FileStatus.SCANNING),
        FileStatus.SCANNING, Set.of(FileStatus.ACCEPTED, FileStatus.REJECTED),
        FileStatus.ACCEPTED, Set.of(FileStatus.ARCHIVED, FileStatus.DELETION_REQUESTED),
        FileStatus.ARCHIVED, Set.of(FileStatus.DELETION_REQUESTED),
        FileStatus.DELETION_REQUESTED, Set.of(FileStatus.DELETED),
        FileStatus.REJECTED, Set.of(FileStatus.DELETED),
        FileStatus.DELETED, Set.of()
    );

    public void requireAllowed(FileStatus from, FileStatus to) {
        if (!ALLOWED.getOrDefault(from, Set.of()).contains(to)) {
            throw new InvalidLifecycleTransitionException(from, to);
        }
    }
}

public record ConfigSnapshot<T>(
    String version,
    T value,
    Instant loadedAt
) {}

public final class ReloadableConfig<T> {
    private final AtomicReference<ConfigSnapshot<T>> current;

    public ReloadableConfig(ConfigSnapshot<T> initial) {
        this.current = new AtomicReference<>(initial);
    }

    public ConfigSnapshot<T> current() {
        return current.get();
    }

    public void reload(ConfigSnapshot<T> candidate, Predicate<T> validator) {
        if (!validator.test(candidate.value())) {
            throw new InvalidConfigurationException(candidate.version());
        }

        current.set(candidate);
    }
}

public final class SecretValue {
    private final String value;

    private SecretValue(String value) {
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("Secret value is required");
        }
        this.value = value;
    }

    public static SecretValue of(String value) {
        return new SecretValue(value);
    }

    public String revealForUse() {
        return value;
    }

    @Override
    public String toString() {
        return "[REDACTED]";
    }
}

What is the source of truth?
What happens if this operation succeeds halfway?
What retries this command?
What makes retry safe?
What state can become stale?
Who can mutate this value?
How is this audited?
Can we prove the file was not changed?
What happens if config changes during traffic?
What happens if secret expires during traffic?
What happens if old pods and new pods run different config?
What data leaks if logs are exported?
What is the recovery path?
What is the smallest blast radius?
What is the rollback path?