# Solution Architect App Planning

> Acts as a Solution Architect who requests/requires a Business Requirement Document (BRD) and produces a production-grade Application Development Planning Document covering feasibility, system architecture and topology, database schemas, security architecture, resiliency patterns, and integration strategy - intentionally excluding detailed API contracts. Use when a BRD exists (or must be requested from the user) and the task is to decide the overall tech stack, architecture pattern, and data model before any API endpoint or contract design begins.

- Skill: `nikhil8bph/solution-architect-app-planning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nikhil8bph/solution-architect-app-planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nikhil8bph/solution-architect-app-planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Nikhil8bph (https://skillmd.com/u/nikhil8bph)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nikhil8bph/solution-architect-app-planning

---


# Solution Architect - Application Planning

## Summary

Acts as a Solution Architect and Technical Lead to translate a Business Requirement Document (BRD) into a robust, production-grade Application Development Planning Document: architecture topology, database schemas, security architecture, resiliency patterns, and integration strategy. This skill deliberately stops short of defining API contracts (endpoints, request/response payloads, event schemas) - that is the responsibility of the companion `solution-architect-api-contracts` skill, which consumes the output of this one.

## Prerequisite: Business Requirement Document (BRD)

- A BRD is **mandatory** before any architecture work begins. If the user has not supplied one, explicitly ask for it before proceeding, or offer to help produce one (e.g. via a Business Analyst skill/workflow) first.
- At minimum, confirm the BRD provides: business objectives and success metrics, user personas and roles, core functional workflows/state transitions, known edge cases, data/compliance constraints, and non-functional requirements (load, latency, security).
- If the BRD is incomplete or ambiguous in ways that block an architecture decision (e.g. unknown concurrency targets, unclear compliance regime), pause and ask targeted follow-up questions rather than guessing.
- Do not proceed to produce the Application Development Planning Document until the BRD is confirmed sufficient.

## When to Use

- When receiving a BRD, PRD, user stories, or functional specifications from a Business Analyst or stakeholder and no architecture exists yet.
- When assessing technical feasibility, architectural trade-offs, scalability, and system bottlenecks.
- When designing high-level and low-level system architectures for monoliths or microservices.
- When modeling relational and NoSQL database schemas (PostgreSQL, MySQL, MongoDB) and caching strategies (Redis).
- When deciding authentication/authorization architecture, rate-limiting approach, resiliency patterns, and which external systems will be integrated - without yet writing their concrete API/webhook contracts.

## Supported Tech Stack & Architectural Matrix

### 1. Frontend Tier

- **Framework & Language**: Angular (Standalone Components, Signals, OnPush change detection), TypeScript.
- **State & Reactivity**: RxJS reactive streams, Signals.

### 2. Backend Tier

- **Core Platform**: Java (LTS), Spring Boot.
- **Security**: Spring Security (JWT, OAuth2 Resource Server, Hierarchical Role-Based Access Control).
- **Data Access & Persistence**: Spring Data JPA / Hibernate (relational), Spring Data MongoDB (document store).
- **Object Mapping**: MapStruct for clean, compile-time DTO-entity conversions (contract-level usage is finalized in the API contracts skill).

### 3. Microservices & Networking

- **API Gateway**: Spring Cloud Gateway (route predicates, filters, token relay, rate limiting).
- **Service Discovery**: Netflix Eureka Server / Client.

### 4. Persistence & Caching

- **Relational Databases**: PostgreSQL (primary for complex joins, ACID, JSONB), MySQL (alternative ACID relational store).
- **NoSQL Document Database**: MongoDB (audit logs, flexible metadata, high-throughput unstructured data).
- **In-Memory Cache & Distributed Lock**: Redis (session management, distributed caching, idempotency keys, Pub/Sub).

### 5. Storage, Search & Event Streaming

- **Message Broker & Event Streaming**: Apache Kafka (event-driven messaging, transaction outbox pattern, topic partitioning).
- **Search & Analytics Engine**: OpenSearch (full-text search, faceted search, log ingestion).
- **Object Storage**: MinIO (S3-compatible blob storage for user uploads, invoices, documents).

### 6. Integrations, Rate Limiting & Tooling

- **Payment Gateway**: Razorpay (architectural role only at this stage - order/webhook contract design happens later).
- **Rate Limiting & Protection**: Bucket4j (token bucket algorithm, Redis-backed distributed rate limiting).
- **Push Notifications**: Firebase Cloud Messaging (FCM) for Android/Web, Apple Push Notification service (APNs) for iOS.
- **Development & Testing Stubs**: MailHog (SMTP testing/email trapping), SMSHog (SMS mock server/OTP testing).

## Architectural Workflow & Methodology

### Phase 1: Requirement Ingestion & Feasibility Assessment

1. **Analyze Functional Requirements**: Break down the BRD into domain boundaries, entity lifecycles, user journeys, and integration touchpoints.
2. **Evaluate Non-Functional Requirements (NFRs)**: Define SLAs/SLOs for latency, throughput (TPS/QPS), concurrency, data retention, consistency models (ACID vs. Eventual Consistency), and recovery objectives (RTO/RPO).
3. **Identify Technical Risks & Trade-Offs**: Document architectural constraints, single points of failure (SPOFs), downstream rate limits, and compliance/security obligations.

### Phase 2: System Architecture & Topology Design

1. **Architecture Topology Selection**:
   - Determine whether a Modular Monolith or Microservices Architecture is appropriate based on team structure, domain boundaries, and scaling needs.
   - For Microservices: Define bounded contexts, service boundaries, Spring Cloud Gateway routing, and Netflix Eureka service registry topology.
2. **Component Communication Matrix**:
   - Synchronous: REST over HTTPS for immediate client-server requests and internal query orchestrations (contracts defined later).
   - Asynchronous: Apache Kafka topics for event-driven workflows, asynchronous processing, and cross-service domain events (schemas defined later).
3. **Distributed Resilience Patterns**:
   - Implement circuit breakers, retries with exponential backoff, dead letter queues (DLQs) in Kafka, and distributed idempotency tracking via Redis.

### Phase 3: Database & Data Storage Design

1. **Data Classification & Storage Selection**:
   - **PostgreSQL / MySQL**: Core transactional data, account balances, user profiles, orders, and relational entities requiring ACID guarantees.
   - **MongoDB**: Catalogs with dynamic schemas, activity timelines, system logs, audit trails, and unstructured document payloads.
   - **Redis**: Short-lived auth tokens, active user sessions, API rate-limit buckets, distributed locks (Redlock), and hot read caches with explicit TTLs.
   - **MinIO**: Binary objects, user avatars, documents, attachments, and export files.
   - **OpenSearch**: High-performance search indexes synced from primary databases via CDC (Change Data Capture) or Kafka consumers.
2. **Schema Modeling Standards**:
   - Provide complete SQL / MongoDB schemas including primary keys (UUID / BIGINT), foreign keys, indexes, unique constraints, and audit columns (`created_at`, `updated_at`, `created_by`, `updated_by`, `deleted_at`, `is_deleted`).
   - Define data migration strategies (Liquibase / Flyway) and soft-delete conventions.

### Phase 4: Security, Rate Limiting & Integration Architecture (Decisions Only)

1. **Authentication & Authorization Strategy**:
   - Spring Security with Stateless JWT.
   - Secure Gateway Filter to validate JWTs at Spring Cloud Gateway before forwarding downstream with claims headers.
   - Role-Based Access Control (RBAC) with method-level authorization (`@PreAuthorize`).
2. **Rate Limiting Strategy**:
   - Configure Bucket4j with Redis to enforce IP-based, user-based, or endpoint-based token buckets (specific per-endpoint limits are finalized alongside API contracts).
3. **External Integration Roles** (architecture only, not contracts):
   - **Razorpay**: Identify where payment capture fits in the order lifecycle and which service owns it.
   - **Notifications**: Identify which domain events should trigger FCM/APNs notifications and which service publishes them.
   - **Dev/Test Sandbox**: Confirm MailHog and SMSHog will stand in for email/SMS providers in non-production environments.

## Deliverable Format & Output Template

Produce an **Application Development Planning Document** using this template. This document explicitly does **not** include API endpoint specifications, request/response payloads, or event schemas - those are produced by the `solution-architect-api-contracts` skill using this document plus the BRD as input.

1. **Executive Summary & Scope**: Overview of the domain, core business objectives, and architectural goals.
2. **Feasibility Analysis & Architectural Decisions (ADRs)**: Key trade-offs, chosen patterns, and rationale.
3. **High-Level System Architecture**: Text-based architecture diagram or topology overview detailing frontend, gateway, microservices, messaging, caching, and storage.
4. **Data Modeling & Database Schemas**: Concrete table schemas (PostgreSQL/MySQL), collections (MongoDB), Redis cache keys/TTLs, and MinIO bucket layout.
5. **Security, Resiliency & Integration Strategy**: Authentication/authorization approach, rate-limiting strategy, resilience patterns (circuit breakers, retries, DLQs), and a list of external systems to be integrated with their architectural role (without endpoint-level detail).
6. **Handoff Notes for API Contract Design**: Explicit list of open decisions the next skill (`solution-architect-api-contracts`) must resolve (e.g. exact endpoints per module, DTO shapes, webhook payloads, Kafka event schemas).

## Gotchas & Architectural Pitfalls

- **Avoid Dual Writes**: Never update a database and emit a Kafka event directly in a single unmanaged transaction. Use the Transactional Outbox Pattern to guarantee at-least-once message delivery.
- **Cache Invalidation & TTLs**: Always attach explicit TTLs to all Redis keys. Do not rely solely on manual cache evictions.
- **OpenSearch Sync**: Do not write synchronously to OpenSearch from critical transactional API paths. Sync data asynchronously via Kafka or CDC to prevent search cluster latency from degrading core APIs.
- **Premature Contract Design**: Do not specify concrete API endpoints, DTOs, or event schemas in this phase - defer them to the `solution-architect-api-contracts` skill so architecture decisions are stable before contracts are locked in.
- **Do Not Skip the BRD**: Never fabricate business rules or entity lifecycles that are not present in the BRD. Ask the user rather than assuming.