AWS Cloud Architecture Context

This skill provides specialized context and guidance for working with ViewDocs Cloud, a multi-tenant serverless document management system built on AWS.

What This Skill Does

Loads comprehensive architectural context for the ViewDocs Cloud migration project, including:

When to Use This Skill

Use this skill when working on:

Instructions

When this skill is loaded, you will have access to detailed context about:

1. Project Overview

2. Technology Stack

**Backend:**

**Frontend:**

**Infrastructure:**

3. Key Architecture Patterns

**Tenant Isolation:**

**Serverless & Non-VPC (ADR-012):**

**Archive Abstraction:**

**MailRoom Integration (ADR-013):**

**Event-Driven:**

**Bulk Download:**

4. DynamoDB Table Design

Single-table design with access patterns:

Key schema pattern: `PK=TENANT#<tenantId>`, `SK=<EntityType>#<ID>`

GSIs for cross-partition queries (user activity, document listings)

5. Security Guidelines

**Authentication:**

**Authorization:**

**Secrets Management:**

**Encryption:**

6. Development Commands

**CDK Infrastructure:**

```bash

cdk synth # Synthesize CloudFormation

cdk deploy --all --context env=dev # Deploy to dev

cdk deploy --all --context env=uat # Deploy to UAT

cdk deploy --all --context env=prod # Deploy to prod (Jenkins only)

```

**Backend Lambda:**

```bash

npm install # Install dependencies

npm test # Run unit tests

npm test -- --coverage # Run with coverage

npm run lint # Lint code

npm run build # Build for deployment

```

**Frontend Angular:**

```bash

npm start # Dev server (localhost:4200)

npm test # Unit tests

npm run e2e # E2E tests

npm run build:prod # Production build

```

7. Deployment Strategy

**CI/CD Pipeline Flow:**

1. Bitbucket PR merged to `develop`

2. Jenkins webhook trigger

3. Build & test

4. Deploy dev (jenkins-dev-agent)

5. Integration tests

6. Heat Call approval (UAT)

7. Deploy UAT (jenkins-uat-agent)

8. E2E + load tests

9. Heat Call approval (Production)

10. Deploy prod blue-green (jenkins-prod-agent)

11. Canary monitoring → gradual rollout

**Blue-Green Deployment:**

**Heat System Integration:**

8. Testing Strategy

**Unit Tests:**

**Integration Tests:**

**E2E Tests:**

**Load Tests:**

9. Monitoring & Alerting

Key metrics to monitor:

10. Repository Structure

```

/

├── docs/architecture/ # TOGAF + C4 architecture docs

├── infrastructure/ # AWS CDK code (stacks + constructs)

├── backend/ # Lambda functions (TypeScript)

│ ├── src/functions/ # Lambda handlers

│ ├── src/services/ # Business logic

│ └── src/middleware/ # Auth, logging, error handling

├── frontend/ # Angular application

│ └── src/app/features/ # Feature modules (documents, search, admin)

└── intent-statement.md # Business requirements

```

Usage Guidelines

1. **Always Consider Multi-Tenancy**: Every Lambda function must extract tenant_id and enforce isolation

2. **Follow Non-VPC Pattern**: Lambda functions connect to AWS services via public endpoints with IAM

3. **Use Single-Table Design**: All DynamoDB queries must include tenant_id in partition key

4. **Implement Audit Logging**: All document operations must log to audit table with TTL

5. **Follow Security Guidelines**: Never hardcode credentials; use Secrets Manager and least-privilege IAM

6. **Test Thoroughly**: Unit tests (80% coverage), integration tests, E2E tests, and load tests required

7. **Follow Deployment Process**: Heat System approvals required for UAT and Production

8. **Monitor Proactively**: Set up CloudWatch alarms for key metrics before deploying

Important Notes

Examples

**Creating a new Lambda function:**

1. Add handler in `backend/src/functions/`

2. Extract tenant_id from event.headers.host

3. Implement authorization check against DynamoDB ACLs

4. Add audit logging to DynamoDB with TTL

5. Emit event to EventBridge for downstream processing

6. Write unit tests with mocked dependencies (80% coverage target)

7. Add CDK stack definition in `infrastructure/lib/stacks/`

8. Deploy via Jenkins pipeline with Heat approval

**Adding a new DynamoDB access pattern:**

1. Design partition key with `TENANT#<tenantId>` prefix

2. Design sort key with entity type and ID

3. Consider if GSI is needed for cross-partition queries

4. Update CDK stack to add GSI if required

5. Implement query logic with tenant isolation

6. Add integration test for new access pattern

**Integrating a new on-premise system:**

1. Design abstraction interface matching existing archive clients

2. Implement SOAP or REST client with retry logic

3. Store credentials in Secrets Manager per tenant

4. Add Direct Connect routing via public VIF + IPsec VPN

5. Add EventBridge integration for audit events

6. Test with canary tenant in UAT environment