Microservices Overview¶

NeoCore is composed of 60+ Spring Boot microservices, each owning a specific banking domain. All services connect to a single PostgreSQL instance (neocoredb) using schema-per-service isolation.

Core Services (Active Development)¶

Service	Port	Domain	Schema
`api-gateway`	8080	Request routing, JWT auth	—
`deposit-service`	8081	Term deposits, recurring, thrift	`deposit`
`customer-service`	8082	Customer master, KYC	`customer`
`product-service`	8083	Product config, interest rates	`product`
`share-service`	8086	Share accounts, MDS chit fund	`share`
`generalledger-service`	8088	GL heads, balance sheet	`gl`
`system-setup-service`	8089	Branches, users, screens, holidays	`syssetup`
`bankandbranch-service`	8090	Bank and branch master data	`bankbranch`
`transaction-service`	TBD	Cash & transfer transactions	`transaction`
`common-service`	—	Flyway DB migrations (shared)	—

Pending Services¶

The following services are planned but not yet implemented:

Category	Services
Loans	`termloan-service`, `goloan-service`, `staffloan-service`, `pigmyloan-service`
Accounts	`operativeaccount-service`, `savingsaccount-service`
HR / Payroll	`employee-service`, `payroll-service`
Compliance	`atm-service`, `locker-service`, `clearing-service`, `forex-service`
Reporting	`jasperreport-service`
Infrastructure	`inventory-service`, `messaging-service`

Standard Service Structure¶

Every microservice follows this Maven project layout:

{service-name}/
├── src/main/java/com/arcat/{domain}/
│   ├── {Service}Application.java       # Spring Boot entry point
│   ├── api/                            # REST controllers
│   ├── service/                        # Business logic (thin wrappers)
│   ├── repository/                     # JPA repositories / DB function calls
│   ├── dto/                            # Request/response DTOs
│   ├── model/                          # JPA entities
│   ├── client/                         # Feign clients (inter-service calls)
│   └── config/                         # Spring config, security
├── src/main/resources/
│   └── application.yml                 # Port, DB, Eureka config
└── pom.xml

Inter-Service Communication¶

Services communicate via HTTP using Spring's RestTemplate or Feign clients. All calls go through the API Gateway, which handles:

JWT token validation
Route resolution via Eureka
Load balancing

sequenceDiagram
    participant FE as Frontend
    participant GW as API Gateway
    participant CS as customer-service
    participant DS as deposit-service

    FE->>GW: POST /api/deposits (Bearer token)
    GW->>GW: Validate JWT
    GW->>DS: Route to deposit-service
    DS->>CS: GET /api/customers/{id} (Feign client)
    CS-->>DS: Customer data
    DS-->>FE: Deposit created response

Security Model¶

All services use ShowcaseBearerAuthenticationFilter to validate JWT tokens on every request. The token is issued by the API Gateway after login and carries user ID, branch, and role claims.

Running a Service Locally¶

# 1. Start PostgreSQL via Docker
docker-compose up -d

# 2. Build the service
cd cbms-ai-microservices/microservices/{service-name}
mvn package -DskipTests

# 3. Run the JAR
java -jar target/{service-name}-*.jar

Alternatively, use the provided start-{service}.bat scripts at the root of cbms-ai-microservices/.