# christyjohn/vilka_mvp architecture

> Architecture diagram of the GitHub repository christyjohn/vilka_mvp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/christyjohn/vilka_mvp
- Repository: https://github.com/christyjohn/vilka_mvp

## Overview

This repo is a small microservice-style B2C platform split into three independently runnable Spring Boot applications: `identity`, `marketplace` (catalog), and `subscription`. Each service has its own `pom.xml`, Maven wrapper, application entry point, configuration, tests, and Flyway migrations, so they can be built and deployed separately.

The `identity` service is the user/account boundary. It owns authentication (`AuthController`, `AuthService`), user management (`UserController`, `UserService`), profiles, addresses, and countries. It also contains JWT support, Spring Security configuration, a custom user details service, and an internal API-key filter, which suggests it serves both public auth flows and protected internal service calls.

The `marketplace` service is the catalog boundary. Its only domain shown is `offering`, with a standard controller-service-repository-entity stack for offering lifecycle operations. It also has its own security configuration, which means it is a protected domain service rather than a public shared library.

The `subscription` service is the orchestration boundary. It owns subscription data and business logic, but it also depends on external services through Feign clients: `MarketplaceClient` and `UserClient`. That makes it the main integration point that validates or enriches subscription operations using catalog and identity data.

Across all three services, the internal structure is consistent: controllers expose HTTP APIs, services contain business rules, repositories handle persistence, entities map to database tables, DTOs shape request/response payloads, and mappers convert between layers. This makes the codebase easy to diagram as repeated vertical slices per bounded context.

Persistence is relational and migration-driven. Each service has `src/main/resources/db/migration` with versioned SQL scripts, indicating Flyway-managed schema evolution. Entities such as `User`, `Profile`, `Address`, `Country`, `OfferingEntity`, and `Subscription` are the source of truth for each service’s database model.

The main data flow in `identity` is: authentication requests come into `AuthController`, user/account state is managed through service and repository layers, and JWT-related utilities are used to secure downstream requests. The presence of `InternalUserController` and `InternalApiKeyFilter` indicates separate internal endpoints for other services to call without using the public auth flow.

The main data flow in `subscription` is: `SubscriptionController` accepts subscription requests, `SubscriptionService` coordinates local persistence plus remote lookups through Feign, and the service stores subscription state in its own database. This service therefore bridges local transactional state with remote dependency checks.

Security is service-local rather than centralized. Each app has its own `SecurityConfig`, and the `subscription` and `marketplace` services also expose `SecurityUtils`, likely for extracting the authenticated principal or claims from the security context. The architecture suggests JWT-based authentication established in `identity` and consumed by the other services.

Common platform code is repeated inside each service, not shared as a separate module. The shared patterns include `ApiException`, `ErrorCode`, `ErrorResponse`, `GlobalExceptionHandler`, and `StartupTimer`. These provide consistent error handling and startup instrumentation across services.

At a high level, the system boundary looks like this: `identity` owns who the user is, `marketplace` owns what can be subscribed to, and `subscription` owns the relationship between a user and an offering. The important cross-service dependency arrows are `subscription -> identity` and `subscription -> marketplace`; the other services do not appear to depend on each other directly.

Main entry points: [`subscription/src/main/java/com/vilka/app/subscription/SubscriptionApplication.java`](https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/SubscriptionApplication.java) (Subscription App), [`identity/src/main/java/com/vilka/app/identity/IdentityApplication.java`](https://github.com/christyjohn/vilka_mvp/blob/main/identity/src/main/java/com/vilka/app/identity/IdentityApplication.java) (Identity App), [`subscription/src/main/java/com/vilka/app/subscription/service/SubscriptionService.java`](https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/service/SubscriptionService.java) (Subscription Core), [`marketplace/src/main/java/com/vilka/app/catalog/MarketplaceApplication.java`](https://github.com/christyjohn/vilka_mvp/blob/main/marketplace/src/main/java/com/vilka/app/catalog/MarketplaceApplication.java) (Marketplace App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity"]
  node_identity_app(("Identity App<br/>spring boot app"))
  node_identity_auth["Auth API<br/>auth controller/service"]
  node_identity_accounts["User API<br/>user/profile domain"]
  node_identity_security["Security<br/>jwt and api-key"]
  node_identity_data[("Identity Store<br/>repositories and migrations<br/>[BaseEntity.java]")]
  node_identity_common["Shared Common<br/>errors and util"]
end

subgraph group_marketplace["Marketplace"]
  node_marketplace_app(("Marketplace App<br/>spring boot app"))
  node_marketplace_offerings["Offering API<br/>offering controller/service"]
  node_marketplace_security["Security<br/>service auth"]
  node_marketplace_data[("Catalog Store<br/>repository and flyway")]
  node_marketplace_common["Shared Common<br/>errors and util"]
end

subgraph group_subscription["Subscription"]
  node_subscription_app(("Subscription App<br/>spring boot app"))
  node_subscription_api["Subscription API<br/>controller and mapper"]
  node_subscription_core["Subscription Core<br/>service and repository"]
  node_subscription_clients{{"Feign Clients<br/>marketplace and user clients"}}
  node_subscription_security["Security<br/>service auth"]
  node_subscription_data[("Subscription Store<br/>repository and flyway<br/>[Subscription.java]")]
  node_subscription_common["Shared Common<br/>errors and util"]
end

node_identity_app -->|"hosts"| node_identity_auth
node_identity_app -->|"hosts"| node_identity_accounts
node_identity_app -->|"configures"| node_identity_security
node_identity_app -->|"persists"| node_identity_data
node_identity_app -.->|"uses"| node_identity_common
node_identity_auth -->|"authenticates"| node_identity_security
node_identity_accounts -->|"stores"| node_identity_data
node_marketplace_app -->|"hosts"| node_marketplace_offerings
node_marketplace_app -->|"configures"| node_marketplace_security
node_marketplace_app -->|"persists"| node_marketplace_data
node_marketplace_app -.->|"uses"| node_marketplace_common
node_marketplace_offerings -->|"stores"| node_marketplace_data
node_marketplace_offerings -->|"guards"| node_marketplace_security
node_subscription_app -->|"hosts"| node_subscription_api
node_subscription_app -->|"runs"| node_subscription_core
node_subscription_app -->|"connects"| node_subscription_clients
node_subscription_app -->|"configures"| node_subscription_security
node_subscription_app -->|"persists"| node_subscription_data
node_subscription_app -.->|"uses"| node_subscription_common
node_subscription_api -->|"delegates"| node_subscription_core
node_subscription_core -->|"validates"| node_subscription_clients
node_subscription_core -->|"stores"| node_subscription_data
node_subscription_core -.->|"reads context"| node_subscription_security
node_subscription_clients -->|"calls"| node_marketplace_offerings
node_subscription_clients -->|"calls"| node_identity_accounts
node_identity_security -.->|"supports"| node_identity_auth

click node_identity_app "https://github.com/christyjohn/vilka_mvp/blob/main/identity/src/main/java/com/vilka/app/identity/IdentityApplication.java"
click node_identity_auth "https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/auth"
click node_identity_accounts "https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/user"
click node_identity_security "https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/auth/security"
click node_identity_data "https://github.com/christyjohn/vilka_mvp/blob/main/identity/src/main/java/com/vilka/app/identity/common/base/entity/BaseEntity.java"
click node_identity_common "https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/common"
click node_marketplace_app "https://github.com/christyjohn/vilka_mvp/blob/main/marketplace/src/main/java/com/vilka/app/catalog/MarketplaceApplication.java"
click node_marketplace_offerings "https://github.com/christyjohn/vilka_mvp/tree/main/marketplace/src/main/java/com/vilka/app/catalog/offering"
click node_marketplace_security "https://github.com/christyjohn/vilka_mvp/blob/main/marketplace/src/main/java/com/vilka/app/catalog/common/config/SecurityConfig.java"
click node_marketplace_data "https://github.com/christyjohn/vilka_mvp/blob/main/marketplace/src/main/java/com/vilka/app/catalog/offering/entity/OfferingEntity.java"
click node_marketplace_common "https://github.com/christyjohn/vilka_mvp/tree/main/marketplace/src/main/java/com/vilka/app/catalog/common"
click node_subscription_app "https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/SubscriptionApplication.java"
click node_subscription_api "https://github.com/christyjohn/vilka_mvp/tree/main/subscription/src/main/java/com/vilka/app/subscription/controller"
click node_subscription_core "https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/service/SubscriptionService.java"
click node_subscription_clients "https://github.com/christyjohn/vilka_mvp/tree/main/subscription/src/main/java/com/vilka/app/subscription/client"
click node_subscription_security "https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/common/config/security/SecurityConfig.java"
click node_subscription_data "https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/entity/Subscription.java"
click node_subscription_common "https://github.com/christyjohn/vilka_mvp/tree/main/subscription/src/main/java/com/vilka/app/subscription/common"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_identity_app,node_identity_auth,node_identity_accounts,node_identity_security,node_identity_data,node_identity_common toneBlue
class node_marketplace_app,node_marketplace_offerings,node_marketplace_security,node_marketplace_data,node_marketplace_common toneAmber
class node_subscription_app,node_subscription_api,node_subscription_core,node_subscription_clients,node_subscription_security,node_subscription_data,node_subscription_common toneMint
```

## Components

### Identity

User and account boundary

- [Identity App](https://github.com/christyjohn/vilka_mvp/blob/main/identity/src/main/java/com/vilka/app/identity/IdentityApplication.java): spring boot app · Identity service entry point · `identity/src/main/java/com/vilka/app/identity/IdentityApplication.java`
- [Auth API](https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/auth): auth controller/service · Login, registration, password reset, token issuance · `identity/src/main/java/com/vilka/app/identity/auth`
- [User API](https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/user): user/profile domain · Users, profiles, addresses, and countries · `identity/src/main/java/com/vilka/app/identity/user`
- [Security](https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/auth/security): jwt and api-key · Spring Security, JWT utilities, internal API-key filter · `identity/src/main/java/com/vilka/app/identity/auth/security`
- [Identity Store](https://github.com/christyjohn/vilka_mvp/blob/main/identity/src/main/java/com/vilka/app/identity/common/base/entity/BaseEntity.java): repositories and migrations · Entity mappings and Flyway-managed schema · `identity/src/main/java/com/vilka/app/identity/common/base/entity/BaseEntity.java`
- [Shared Common](https://github.com/christyjohn/vilka_mvp/tree/main/identity/src/main/java/com/vilka/app/identity/common): errors and util · Exception model, global handler, startup timing · `identity/src/main/java/com/vilka/app/identity/common`

### Marketplace

Catalog boundary

- [Marketplace App](https://github.com/christyjohn/vilka_mvp/blob/main/marketplace/src/main/java/com/vilka/app/catalog/MarketplaceApplication.java): spring boot app · Catalog service entry point · `marketplace/src/main/java/com/vilka/app/catalog/MarketplaceApplication.java`
- [Offering API](https://github.com/christyjohn/vilka_mvp/tree/main/marketplace/src/main/java/com/vilka/app/catalog/offering): offering controller/service · Offering lifecycle operations · `marketplace/src/main/java/com/vilka/app/catalog/offering`
- [Security](https://github.com/christyjohn/vilka_mvp/blob/main/marketplace/src/main/java/com/vilka/app/catalog/common/config/SecurityConfig.java): service auth · Service-local security and principal helpers · `marketplace/src/main/java/com/vilka/app/catalog/common/config/SecurityConfig.java`
- [Catalog Store](https://github.com/christyjohn/vilka_mvp/blob/main/marketplace/src/main/java/com/vilka/app/catalog/offering/entity/OfferingEntity.java): repository and flyway · Offering entity persistence and schema migration · `marketplace/src/main/java/com/vilka/app/catalog/offering/entity/OfferingEntity.java`
- [Shared Common](https://github.com/christyjohn/vilka_mvp/tree/main/marketplace/src/main/java/com/vilka/app/catalog/common): errors and util · Exception handling and startup timing · `marketplace/src/main/java/com/vilka/app/catalog/common`

### Subscription

Orchestration boundary

- [Subscription App](https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/SubscriptionApplication.java): spring boot app · Subscription service entry point · `subscription/src/main/java/com/vilka/app/subscription/SubscriptionApplication.java`
- [Subscription API](https://github.com/christyjohn/vilka_mvp/tree/main/subscription/src/main/java/com/vilka/app/subscription/controller): controller and mapper · Subscription request/response boundary · `subscription/src/main/java/com/vilka/app/subscription/controller`
- [Subscription Core](https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/service/SubscriptionService.java): service and repository · Subscription business logic and local persistence · `subscription/src/main/java/com/vilka/app/subscription/service/SubscriptionService.java`
- [Feign Clients](https://github.com/christyjohn/vilka_mvp/tree/main/subscription/src/main/java/com/vilka/app/subscription/client): marketplace and user clients · Remote lookups against catalog and identity · `subscription/src/main/java/com/vilka/app/subscription/client`
- [Security](https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/common/config/security/SecurityConfig.java): service auth · Service-local security and principal helpers · `subscription/src/main/java/com/vilka/app/subscription/common/config/security/SecurityConfig.java`
- [Subscription Store](https://github.com/christyjohn/vilka_mvp/blob/main/subscription/src/main/java/com/vilka/app/subscription/entity/Subscription.java): repository and flyway · Subscription entity persistence and schema migration · `subscription/src/main/java/com/vilka/app/subscription/entity/Subscription.java`
- [Shared Common](https://github.com/christyjohn/vilka_mvp/tree/main/subscription/src/main/java/com/vilka/app/subscription/common): errors and util · Exception handling and startup timing · `subscription/src/main/java/com/vilka/app/subscription/common`

## Connections

- Identity App → Auth API: hosts · Bootstraps public authentication flows
- Identity App → User API: hosts · Bootstraps account management APIs
- Identity App → Security: configures · Installs JWT and internal access controls
- Identity App → Identity Store: persists · Owns the identity database model
- Identity App → Shared Common: uses · Shares error handling and startup utilities
- Auth API → Security: authenticates · Login and token issuance depend on security components
- User API → Identity Store: stores · Users, profiles, addresses, and countries are persisted here
- Marketplace App → Offering API: hosts · Bootstraps catalog APIs
- Marketplace App → Security: configures · Protects catalog endpoints
- Marketplace App → Catalog Store: persists · Owns catalog schema and data
- Marketplace App → Shared Common: uses · Shares error handling and startup utilities
- Offering API → Catalog Store: stores · Offering operations write through repository layer
- Offering API → Security: guards · Relies on service-local security context
- Subscription App → Subscription API: hosts · Bootstraps subscription APIs
- Subscription App → Subscription Core: runs · Wires subscription orchestration
- Subscription App → Feign Clients: connects · Configures remote service clients
- Subscription App → Security: configures · Protects subscription endpoints
- Subscription App → Subscription Store: persists · Owns subscription database state
- Subscription App → Shared Common: uses · Shares error handling and startup utilities
- Subscription API → Subscription Core: delegates · HTTP requests flow into business logic
- Subscription Core → Feign Clients: validates · Checks catalog and user data remotely
- Subscription Core → Subscription Store: stores · Subscription records are saved locally
- Subscription Core → Security: reads context · Uses security helpers for caller identity
- Feign Clients → Offering API: calls · Looks up offerings in marketplace
- Feign Clients → User API: calls · Looks up users in identity
- Security → Auth API: supports · JWT and API-key support public and internal auth flows