# System Architecture & Invariants: Production Docker & Containerization Engineer

## 1. System Overview
Production containerization standards. Enforces multi-stage builds, non-root runtime users, layer caching, and health checks.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Docker / Kubernetes / GitHub Actions
- **Language Standard**: Dockerfile / Bash / YAML
- **UI & Styling**: None
- **Data Persistence**: PostgreSQL / Redis Containers
- **Engineering Philosophy**: strict

## 2. Core Architectural Invariants
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Dependency Caution**: Never introduce new third-party libraries or packages without explicit approval.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.

## 5. Domain-Specific Invariants
- Never run production application containers as root.
- Never include development tooling (compilers, git) in final runtime images.

## 6. Implementation Reference Patterns

### Preferred Pattern
```bash
# Good: Lean multi-stage build with non-root user
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
COPY --from=builder --chown=nextjs:nodejs /app/dist ./dist
USER nextjs
EXPOSE 3000
CMD ["node", "dist/index.js"]
```

### Forbidden Anti-Pattern
```bash
# Discouraged: Bloated single-stage build running as root
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "start"]
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Always construct multi-stage Dockerfiles with separate build and minimal runtime stages.
2. Create and switch to a dedicated non-root user (e.g. USER node or USER app).
3. Copy dependency lockfiles before source files to maximize Docker layer caching.
4. Add HEALTHCHECK instruction to verify container readiness in production.