PolyShop
A source-audited service-oriented commerce lab with explicit boundaries, shared contracts, and documented distributed-workflow designs.
- Role
- Systems/backend engineer
- Sources
- 1 grouped repositories
Problem
Explore how an e-commerce system can separate identity, commerce domains, gateway concerns, shared contracts, infrastructure, and verification assets.
Constraints
- The public main snapshot must be read as the evidence boundary; README and design documents are not treated as runtime proof.
- Implemented auth and narrow messaging evidence must remain distinct from scaffolded services and planned distributed workflows.
- Docker, Kubernetes, Pact, Newman, and k6 assets are recorded without implying that they were built, applied, or executed.
Architecture
Repository service boundaries
Separate auth, product, inventory, order, payment, notification, search, and analytics areas; the audited source shows substantial implementation only in auth.
Gateway and contracts
Pair a gateway module and OpenAPI assets with shared Java, TypeScript, and Python DTO/event helpers; runtime gateway routes remain planned.
Messaging, infrastructure, and QA
Keep one narrow auth audit producer, declared Kafka/Redis/Compose/Kubernetes resources, and Pact/Postman/k6 assets visible with their execution limits.
Evidence record
Mixed classificationsHow the system is split, synchronized, and tested
PolyShop is recorded here as a source-audited distributed-systems lab. The repository has named service, gateway, shared-contract, infrastructure, and QA boundaries, but executable depth is uneven: auth is implemented in this snapshot, while much of the commerce workflow remains scaffolded or documented as design.
Ownership boundaries
The system is easier to reason about when authority, policy, processing, and presentation state have explicit owners.
Authentication and token authority
IMPLEMENTEDauth-service
Own user, role, token, ban, and audit entities; expose authentication/admin controllers; sign RS256 access JWTs and persist hashed token records.
Commerce service boundaries
IMPLEMENTEDservices/*
Separate product, inventory, order, payment, notification, search, and analytics areas are present as repository/build boundaries; most are bootstrap-only in the audited commit.
Public API gateway
DESIGNED / PLANNEDgateway
Provide the intended public entry point and route map, with Spring Cloud Gateway declared as a dependency; executable routes and filters were not found.
Shared contracts and transport helpers
IMPLEMENTEDcommon-libs
Define OpenAPI schemas, request/error shapes, request IDs, idempotency headers, and cross-language event payload types.
Infrastructure and verification assets
NOT TESTEDinfra and qa
Describe local Compose/Kubernetes resources and provide Pact, Postman/Newman, and k6 test assets without claiming that they were executed.
Each boundary is shown with its owner and classification. The arrows describe the evidence-oriented relationship, not a claim that every message moves in one direction.
Transport and boundary contracts
Each boundary describes how data, identity, state, or work crosses between owned parts of the system.
Auth HTTP boundary
IMPLEMENTEDAuthController exposes register, login, refresh, logout, verification, restore, password-reset, and MFA endpoints under /api/v1/auth; Spring Security applies the stateless filter chain.
Auth audit event bridge
IMPLEMENTEDDbAuditService persists an audit event and, when a KafkaTemplate is available, sends one auth.audit message; send exceptions are swallowed by the current implementation.
Gateway-to-service routing
DESIGNED / PLANNEDThe route map is documented for /auth, /products, /inventory, /orders, /payments, /search, and /analytics, but the gateway source contains only the Spring Boot application bootstrap.
Request and idempotency context
DESIGNED / PLANNEDShared Java and TypeScript helpers model X-Request-Id and Idempotency-Key propagation; endpoint-level persistence and conflict handling are not present in the audited source.
Kafka domain messaging
DESIGNED / PLANNEDOrder/payment/stock event names and payload types exist in shared libraries, while source search found no executable consumer and only the narrow auth audit producer.
Workflow modes
The product keeps immediate responses, queued processing, and page previews as distinct contracts.
| Workflow | Mode | Entry point / owner | Processing and result | Evidence |
|---|---|---|---|---|
| Auth registration and access-token lifecycle | SynchronousIMPLEMENTED | POST /api/v1/auth/register, /login, and /refresh Owner: auth-service | Registration persists the user and role; login signs an RS256 access token and stores an access-token entry; refresh validates, revokes, and rotates the opaque refresh token. Result: The controller returns a token response or an explicit validation/authentication error. | auth-controller, auth-jwt, auth-token, auth-domain |
| Optional auth audit emission | AsynchronousIMPLEMENTED | Auth service audit record Owner: auth-service / DbAuditService | Save the audit entity first, then call KafkaTemplate.send with topic auth.audit when the optional bean is available. Result: The database audit record remains the local result; broker delivery is optional and its failure is ignored. | auth-audit-kafka, auth-domain |
| Order, reservation, and payment saga | SynchronousDESIGNED / PLANNED | POST /orders through the intended gateway Owner: order-service as proposed orchestrator | Design documents describe product validation, stock reservation, payment initiation, payment events, and release/cancel compensation; the order-service source is bootstrap-only. Result: The order saga is DESIGNED / PLANNED; an executable orchestrator was not found in this snapshot. | saga-design, communication-design, order-source, event-contracts |
Architecture decisions
Each decision records the boundary it protects and the alternative that was deliberately not chosen.
Keep service boundaries evidence-scoped
ACCEPTED- Decision
- Present the named service directories as repository ownership boundaries, while explicitly showing that only auth has substantial implementation in this snapshot.
- Why
- The directory/build structure is real evidence, but naming a microservice is not enough to imply a running independently implemented service.
- Alternative considered
- Treat every service directory as a completed production component; rejected because source inventory shows bootstrap-only areas.
Limit Kafka wording to executable source
ACCEPTED- Decision
- Describe one optional auth audit producer plus shared event contracts; keep the broader consumer topology as planned.
- Why
- The source contains a KafkaTemplate send but no executable consumer or order-event runtime path.
- Alternative considered
- Publish the README topic topology as implemented; rejected because documentation/configuration is not execution evidence.
Do not publish a Redis runtime claim
ACCEPTED- Decision
- Describe Redis as declared infrastructure/design material and call out that the implemented auth limiter is process-local.
- Why
- Static source search found no Redis client or template; the actual rate limiter uses ConcurrentHashMap.
- Alternative considered
- Repeat the README's sessions/rate-limit/idempotency wording; rejected because it exceeds source evidence.
Keep the order saga as designed
ACCEPTED- Decision
- Show the proposed hybrid saga and compensation boundaries with a DESIGNED / PLANNED badge, not as an implemented workflow.
- Why
- The order service has no controller, domain, repository, producer, or consumer source in the audited commit.
- Alternative considered
- Describe Order Service as the working orchestrator; rejected because only ADR/sequence documentation establishes it.
Keep PolyShop secondary
ACCEPTED- Decision
- Retain `featured: false` and expose the evidence record on the detail page without adding PolyShop to homepage flagship selectors.
- Why
- The audit found useful architecture and QA artifacts, but not enough executable distributed-system or operational evidence for flagship promotion.
- Alternative considered
- Promote PolyShop as a fourth flagship from README claims; rejected pending deeper evidence.
Primary lifecycle
The primary sequence follows input, ownership, processing, result, and cleanup transitions without collapsing synchronous and queued work into one claim.
Register
IMPLEMENTEDRegister
AuthController and UserService
Validate the request, normalize the email, create the user/role records, create an email-verification token, and send the verification message.
Result: A registered account response is returned; persistence is handled by the auth JPA boundary.
Login
IMPLEMENTEDLogin
AuthController and JwtUtil
Authenticate credentials, generate a `kid`-tagged RS256 access JWT, persist its JTI hash, and create a hashed refresh-token record.
Result: The client receives access and refresh tokens with an access-token TTL.
Validate or revoke
IMPLEMENTEDValidate or revoke
JwtAuthenticationFilter and AuthTokenService
Resolve the public key by `kid`, parse the signed token, and require a non-revoked, non-expired persisted access-token entry; logout/revocation updates the record.
Result: Invalid or revoked access tokens do not establish the Spring Security context.
Auth audit send failure
IMPLEMENTEDAuth audit send failure
DbAuditService
Attempt the optional `auth.audit` Kafka send after saving the database audit record.
Result: The local audit save remains; a Kafka send exception is caught and ignored rather than retried or moved to a dead-letter path.
Distributed order workflow
DESIGNED / PLANNEDDistributed order workflow
Order, inventory, payment, and notification services
The design documents describe state transitions, events, reservations, payment outcomes, retries, and compensation.
Result: The documented lifecycle remains a planned boundary because the participating service implementations were not found.
Processing paths
Processing choices are shown with their boundary and limits instead of being collapsed into one generic pipeline claim.
Implemented auth persistence path
IMPLEMENTEDHTTP request → auth controller → JPA entity/repository
Auth owns concrete user, role, token, ban, and audit entities/repositories; token hashes rather than raw opaque tokens are persisted.
Limits
- This source-backed path is limited to auth; the other named domain services do not contain equivalent entities in this snapshot.
Narrow implemented Kafka path
IMPLEMENTEDAuth audit entity → optional KafkaTemplate
DbAuditService sends the audit message to `auth.audit` when a KafkaTemplate bean is available; there is no matching executable consumer in the repository.
Limits
- The send is optional and failure is swallowed.
- No broker or consumer run was performed.
Documented saga path
DESIGNED / PLANNEDGateway → order → inventory/payment → events/compensation
Architecture and ADR documents define a hybrid saga, event names, and compensation steps.
Limits
- No executable order orchestrator, consumer, outbox, reservation handler, or payment integration was found.
QA asset path
NOT TESTEDPact/Postman/k6 files → external test runner
The repository contains contract, API collection, Newman, and k6 assets intended to be run against services.
Limits
- No dependency installation, service startup, test run, report, or threshold result was observed.
Focused code excerpts
Short, source-pinned excerpts make one engineering boundary concrete without reproducing a source file.
Process-local rate-limit buckets
javaprivate record Bucket(AtomicInteger count, long resetAt){}
private final ConcurrentHashMap<String, Bucket> ipMap = new ConcurrentHashMap<>();
public boolean allow(String key, int max, int windowSeconds) {
long now = Instant.now().getEpochSecond();
var b = ipMap.compute(key, (k, old) -> {
if (old == null || old.resetAt() <= now) return new Bucket(new AtomicInteger(1), now + windowSeconds);
old.count().incrementAndGet();
return old;
});
return b.count().get() <= max;
}The executable limiter stores buckets in a process-local ConcurrentHashMap, making the absence of established Redis runtime usage visible without overstating the broader architecture.
Limit: This source excerpt does not establish distributed rate limiting, deployment behavior, or load-test results.
View exact sourcecommit 2e818de0c772fd186da27640933da71d1cda43e5
Failure boundaries
Failure handling is attached to the boundary that owns the response, cleanup, retry, or user-visible state transition.
Access-token validity
IMPLEMENTED- Trigger
- The JWT is missing, has an unknown key ID, cannot be parsed, or has no valid persisted JTI entry.
- Behavior
- JwtAuthenticationFilter leaves the request unauthenticated so Spring Security can reject protected routes.
Auth abuse windows
IMPLEMENTED- Trigger
- IP, email, or phone counters exceed their configured in-memory window; a persistent ban is also present.
- Behavior
- RateLimitFilter returns a 429 response for the relevant rate limit or 403 for a ban.
Audit broker send
IMPLEMENTED- Trigger
- The optional Kafka audit send raises an exception.
- Behavior
- The exception is ignored after the database audit attempt; no retry or dead-letter behavior is implemented in this path.
Gateway reachability
NOT TESTED- Trigger
- A client needs a routed service or a normalized gateway error.
- Behavior
- The intended route/error behavior is described in docs and schemas, but no executable gateway route/filter was found to verify the failure response.
Saga compensation
DESIGNED / PLANNED- Trigger
- Stock reservation or payment would fail or time out in the documented order workflow.
- Behavior
- Release-stock and cancel-order actions are described as planned compensation; the executable handlers were not found.
Evidence, measurements, and limits
Values retain their context, sample, method, and limits so an implementation detail is not mistaken for universal capacity or outcome evidence.
| Evidence | Classification | Result and context | Method / environment / sample | Limitations |
|---|---|---|---|---|
| Implementation depth by service | ACCEPTED | The bounded source inventory found four auth controllers, five auth entities, and five auth repositories; inventory, order, product, search, and gateway have no controllers/entities/repositories in the audited source. Analytics and notification are two-route FastAPI stubs; payment is an Express scaffold. Static review of the public main snapshot at the pinned commit. | Method: Enumerate tracked application source and inspect controller/entity/repository/module declarations. Environment: Fresh read-only shallow clone of public gimesha-adikari/PolyShop main; no services started. Sample: All service and gateway application source files present at commit 2e818de0c772fd186da27640933da71d1cda43e5. |
|
| Pact contract-test assets | NOT TESTED | Pact TypeScript/JavaScript consumer/provider files and package configuration are present; Pact was not executed in this audit. QA asset inspection only. | Method: Read the Pact package, consumer interactions, provider setup/state files, and test runner configuration. Environment: Read-only repository audit; no Pact dependencies or service endpoints started. Sample: Four TypeScript interaction files plus JavaScript/provider assets under qa/pact-tests. |
|
| k6 performance scenarios | NOT TESTED | Smoke, load, stress, spike, and soak scripts exist; load-test.js declares p95<350 ms and failure rate<1% thresholds, but k6 was not run and no output was found. Scenario/threshold inspection only. | Method: Read the k6 options, stages, checks, and thresholds; search the repository for result artifacts. Environment: Read-only repository audit; no gateway or service runtime started. Sample: Five scenario scripts under qa/performance-tests. |
|
| Runtime integration | NOT TESTED | Docker Compose, Dockerfiles, and Kubernetes manifests describe intended resources, but no container build, Compose health check, Kubernetes rollout, or end-to-end request run was performed. Infrastructure artifact review. | Method: Inspect Compose services, image/Dockerfile entrypoints, health checks, Kubernetes probes, and repository completeness. Environment: Read-only source audit; external repository was not modified or deployed. Sample: infra/docker/compose, service/gateway Dockerfiles, and infra/k8s/base manifests. |
|
Failure and recovery stories
Each story connects a symptom to an owned boundary and keeps verification limits visible.
README claims versus the current tree
ACCEPTED- Symptom
- README describes GitHub Actions, a TypeScript SDK path, and broad service capabilities that do not all appear in the current tree.
- Root cause
- The README and design documents contain intended or historical architecture alongside a sparse current implementation snapshot.
- Correction
- The portfolio evidence separates source-backed implementation, test assets, configuration, and design-only material instead of treating the README as runtime proof.
- Verification
- The current root, service inventory, .github path, and referenced files were checked at the pinned commit.
Limitations
- This audit does not rewrite the external README.
- Future commits may change the evidence state.
Redis wording versus the implemented limiter
ACCEPTED- Symptom
- README and infrastructure docs mention Redis for sessions, rate limiting, and idempotency, while the auth limiter uses an in-memory map.
- Root cause
- The Redis design/configuration is ahead of the executable service code in the audited snapshot.
- Correction
- Portfolio wording identifies Redis as planned infrastructure and calls the actual rate limit behavior process-local.
- Verification
- Source search found no RedisTemplate, StringRedisTemplate, Lettuce, Jedis, or RedisConnection use; RateLimitService uses ConcurrentHashMap.
Limitations
- Static search cannot prove behavior in unavailable generated/external code.
- No Redis runtime was started.
Limitations and deferred evidence
- The audited public main commit is source evidence only; no claim is made about later commits or private work.
- Only auth has substantial executable domain/controller/persistence code in this snapshot; the other named services are mostly scaffolds or stubs.
- Gateway routes, gateway authentication, gateway rate limiting, CORS, request IDs, and OpenAPI aggregation are documented or declared but not implemented in the gateway source inspected.
- Kafka evidence is limited to one optional auth audit producer and shared contracts; no executable consumer topology was found.
- Redis client usage was not found; the implemented auth rate limiter is process-local.
- The order saga, compensation, outbox, retries, and dead-letter flow are design material; an executable orchestrator was not found.
- Pact/Postman/Newman/k6 are test assets only in this record; no passing report or measured performance output is attached.
- No `.github/workflows` directory is present at the audited commit, so CI/CD execution is not claimed.
- Docker and Kubernetes artifacts were not built, applied, or health-checked; declarative manifests do not establish deployment.
- No production operation, capacity, scalability, availability, or external-provider outcome is claimed.
Source evidence
Links point to the commits inspected for this page. The classification attached to each claim is more important than the existence of a link alone.
- PolyShop audited main snapshot
Public repository root and current main tree used as the audit boundary.
commit 2e818de0c772fd186da27640933da71d1cda43e5 · 2025-11-19
- PolyShop README
README claims and documented intended architecture, kept separate from executable evidence.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Service directory layout
Named service directories and their public repository boundary.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Service build declarations
Representative Spring Boot/JPA/Cloud dependency declarations for a scaffolded service.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Application source inventory
Bounded audit of controllers, entities, repositories, Python routes, and the payment scaffold.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Order service bootstrap
The audited order-service application entry point; no order controller, domain, repository, or orchestrator accompanies it.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth controller
Register, login, refresh, logout, verification, restore, password reset, and MFA endpoints.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth security configuration
Stateless Spring Security filter chain, public auth paths, and protected routes.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- JWT signing and key resolution
RS256 access-token generation, issuer, key ID, JTI, and public-key resolution boundary.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- JWT authentication filter
JWT parse/JTI validation and Spring Security context population.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Persisted token service
Hashed opaque token creation, refresh rotation, revocation, access-token validity, and cleanup-facing persistence.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth domain entities
Representative auth JPA entity; the auth service also contains User, Role, Ban, and AuditEvent entities.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth user service
User registration/authentication, password handling, role assignment, account state, and token revocation calls.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth repositories
JPA repositories for users, roles, tokens, bans, and audit events.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth rate-limit filter/service
Process-local ConcurrentHashMap counters used by the auth request filter.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth brute-force bans
Database-backed ban lookup/expiry behavior used by the rate-limit filter.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth audit Kafka producer
The narrow executable KafkaTemplate send found during source search.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Auth Kafka dependencies
Spring Kafka and Kafka Streams dependencies declared by auth-service.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Source-level messaging/cache boundary
Repository-wide source audit for Kafka consumers, Redis clients, saga handlers, and outbox implementation.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Shared event contracts
Java order event names/payloads, with parallel TypeScript/Python contract assets.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Shared Java request/error helpers
Request ID filter, shared error handler, event envelope, and common helper boundary.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Shared TypeScript request/event contracts
Request ID, idempotency key, bearer header, DTO, and event type assets.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Shared Python event contracts
Pydantic event envelope and event type constants for Python consumers/producers.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Gateway bootstrap
Gateway application entry point; no route/controller/filter source accompanies it.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Gateway dependencies
Spring Cloud Gateway, load-balancer, actuator, security, and circuit-breaker declarations.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Gateway routing design
Documented route, token, rate-limit, error, and OpenAPI aggregation intent.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Gateway OpenAPI asset
OpenAPI route/schema asset for the intended public gateway surface.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- OpenAPI service contracts
OpenAPI 3.1 schemas for the gateway and named services.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Idempotency design
Intended key, request-hash, response-cache, consumer, payment, and reservation policy.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Order saga design
Documented order state machine, participant responsibilities, timeout, and compensation intent.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Communication design
Documented gateway/service routes, synchronous calls, Kafka topology, and order workflow.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Messaging design
Outbox, processed-events, retry, DLT, envelope, and consumer-idempotency design document.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Outbox design
Design-only outbox schema and publisher algorithm.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Redis design/configuration
Local Redis container and environment declarations, not executable client usage.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Pact test assets
Pact package, consumers, provider setup/states, and verification test files.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Postman collections
Full API collection with service-oriented request examples.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Newman runners
Newman command/report runner scripts; no generated report is attached.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- k6 scenarios
Load scenario with stages/checks/thresholds, plus smoke/stress/spike/soak files.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Docker Compose development topology
Declared local services, databases, Kafka/Zookeeper, Redis, MailHog, and OpenSearch.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Service Dockerfiles
Representative multi-stage image and health-check declarations; not built in this audit.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Kubernetes base manifests
Deployments, Services, ingress, HPAs, ConfigMap, and example Secret manifests.
commit 2e818de0c772fd186da27640933da71d1cda43e5
- Observability design
Documented JSON logging, Prometheus/Grafana/Loki, OpenTelemetry/Jaeger, and SLO intent.
commit 2e818de0c772fd186da27640933da71d1cda43e5
Repository enrichment
Mutable public facts are optional; the project identity above is portfolio-owned.
PolyShop
Service-oriented commerce system
- Updated
- 19 Nov 2025
- Language
- Java
- Stars
- 0
- Forks
- 0
Content notes
- PolyShop was audited against public main at 2e818de0c772fd186da27640933da71d1cda43e5; source-backed and design-only claims are separated in the evidence record.
- The project remains non-featured and absent from homepage flagship selectors; a future evidence pass may revisit promotion without changing this record's source boundary.