Skip to content

Commit a75a262

Browse files
IOhackerIOhacker
committed
MX-263: Create Offices Self Service endpoints
1 parent 9a196f5 commit a75a262

582 files changed

Lines changed: 34761 additions & 55227 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/jfrog-publish.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ jobs:
1414
- name: Set up Java for publishing to Mifos Artifactory
1515
uses: actions/setup-java@v5
1616
with:
17-
java-version: '17'
18-
distribution: 'adopt'
17+
java-version: '21'
18+
distribution: 'zulu'
1919
server-id: central
2020
server-username: ARTIFACTORY_USERNAME
2121
server-password: ARTIFACTORY_PASSWORD
2222
- name: Publish to the Mifos Artifactory
23-
run: mvn -Dmaven.test.skip=true --batch-mode deploy
23+
run: mvn -DskipITs --batch-mode deploy
2424
env:
2525
ARTIFACTORY_USERNAME: ${{ secrets.ARTIFACTORY_USERNAME }}
2626
ARTIFACTORY_PASSWORD: ${{ secrets.ARTIFACTORY_PASSWORD }}

‎.github/workflows/maven-build.yml‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
name: Java CI with Maven
2+
3+
on:
4+
push:
5+
branches: ["develop"]
6+
pull_request:
7+
branches: ["develop"]
8+
9+
jobs:
10+
# ── Job 1: Unit Tests — fast gate (~60s) ─────────────────────────────────
11+
unit-tests:
12+
name: Unit Tests
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Checkout Source Code
17+
uses: actions/checkout@v6
18+
19+
- name: Set up JDK 21
20+
uses: actions/setup-java@v5
21+
with:
22+
java-version: "21"
23+
distribution: "zulu"
24+
cache: "maven"
25+
26+
- name: Run Unit Tests
27+
run: ./mvnw -B clean test -Dspotless.check.skip=true --file pom.xml
28+
29+
- name: Upload Surefire Reports
30+
if: always()
31+
uses: actions/upload-artifact@v7
32+
with:
33+
name: surefire-reports
34+
path: target/surefire-reports/
35+
retention-days: 7
36+
37+
# Upload the .exec binary so the coverage gate can merge it with IT data
38+
- name: Upload Unit Test Coverage Data
39+
if: always()
40+
uses: actions/upload-artifact@v7
41+
with:
42+
name: jacoco-unit-exec
43+
path: target/jacoco.exec
44+
retention-days: 1
45+
46+
# ── Job 2: Integration Tests — Testcontainers (~5 min) ───────────────────
47+
integration-tests:
48+
name: Integration Tests
49+
runs-on: ubuntu-latest
50+
needs: unit-tests
51+
52+
steps:
53+
- name: Checkout Source Code
54+
uses: actions/checkout@v6
55+
56+
- name: Set up JDK 21
57+
uses: actions/setup-java@v5
58+
with:
59+
java-version: "21"
60+
distribution: "zulu"
61+
cache: "maven"
62+
63+
# -Dsurefire.skip=true: compile + run only Failsafe, don't re-run unit tests
64+
- name: Run Integration Tests
65+
run: ./mvnw -B verify -Dspotless.check.skip=true -Dsurefire.skip=true --file pom.xml
66+
67+
- name: Upload Failsafe Reports
68+
if: always()
69+
uses: actions/upload-artifact@v7
70+
with:
71+
name: failsafe-reports
72+
path: target/failsafe-reports/
73+
retention-days: 7
74+
75+
# Upload the IT .exec binary for the coverage merge step
76+
- name: Upload Integration Test Coverage Data
77+
if: always()
78+
uses: actions/upload-artifact@v7
79+
with:
80+
name: jacoco-it-exec
81+
path: target/jacoco-it.exec
82+
retention-days: 1
83+
84+
# ── Job 3: Coverage Gate — merges both .exec files before enforcing ───────
85+
coverage-gate:
86+
name: Coverage Gate
87+
runs-on: ubuntu-latest
88+
needs: [unit-tests, integration-tests]
89+
90+
steps:
91+
- name: Checkout Source Code
92+
uses: actions/checkout@v6
93+
94+
- name: Set up JDK 21
95+
uses: actions/setup-java@v5
96+
with:
97+
java-version: "21"
98+
distribution: "zulu"
99+
cache: "maven"
100+
101+
# Download both .exec files produced in the previous two jobs
102+
- name: Download Unit Test Coverage Data
103+
uses: actions/download-artifact@v8
104+
with:
105+
name: jacoco-unit-exec
106+
path: target/
107+
108+
- name: Download Integration Test Coverage Data
109+
uses: actions/download-artifact@v8
110+
with:
111+
name: jacoco-it-exec
112+
path: target/
113+
114+
# Compile is required so JaCoCo can map bytecode back to source lines
115+
- name: Compile (no tests)
116+
run: ./mvnw -B compile -Dspotless.check.skip=true --file pom.xml
117+
118+
# jacoco:merge reads all *.exec in target/, writes target/jacoco-merged.exec
119+
# jacoco:report generates the human-readable HTML from the merged data
120+
# jacoco:check enforces the ratchet thresholds (see pom.xml enforce-coverage execution)
121+
- name: Merge Coverage Data and Enforce Thresholds
122+
run: |
123+
./mvnw -B jacoco:merge@merge-results jacoco:report@report-merged jacoco:check@enforce-coverage \
124+
-Djacoco.dataFile=target/jacoco-merged.exec \
125+
-Dspotless.check.skip=true \
126+
--file pom.xml
127+
128+
- name: Upload Merged Coverage Report
129+
if: always()
130+
uses: actions/upload-artifact@v7
131+
with:
132+
name: jacoco-merged-report
133+
path: target/site/jacoco-merged/
134+
retention-days: 14

‎.mvn/wrapper/maven-wrapper.properties‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
wrapperVersion=3.3.4
22
distributionType=only-script
3-
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.16/apache-maven-3.9.16-bin.zip
3+
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.15/apache-maven-3.9.15-bin.zip

‎AGENTS.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# AGENTS.md
2+
3+
This file provides context and guidance for AI coding assistants working with the Mifos Self Service Plugin repository.
4+
5+
## Repository Overview
6+
7+
The **Mifos Self Service Plugin** is a Spring Boot plugin that extends Apache Fineract to provide self-service banking capabilities to end users. It enables customers to manage their own accounts, view transactions, and perform banking operations without requiring staff intervention.
8+
9+
### Architecture
10+
11+
- **Framework**: Spring Boot 3 with Java 21
12+
- **Integration**: Apache Fineract 1.15.0-SNAPSHOT
13+
- **Security**: Spring Security with Basic Auth and OAuth2 support
14+
- **Database**: PostgreSQL/MySQL with JPA/EclipseLink
15+
- **API**: RESTful endpoints under `/v1/self`
16+
17+
### Key Components
18+
19+
- **Authentication & Security**: User authentication, permission enforcement, multi-tenant support
20+
- **User Management**: Self-service user registration, profile management
21+
- **Account Management**: Savings accounts, loan accounts, share accounts
22+
- **Product Discovery**: Browse available banking products
23+
- **Reporting**: Financial statements and transaction reports
24+
25+
## Development Environment Setup
26+
27+
### Prerequisites
28+
- Java 21
29+
- Maven 3.6+
30+
- PostgreSQL or MySQL database
31+
- Apache Fineract instance
32+
33+
### Build Commands
34+
```bash
35+
# Build the plugin
36+
./mvnw clean package -Dmaven.test.skip=true
37+
38+
# Run tests
39+
./mvnw test
40+
41+
# Run integration tests
42+
./mvnw verify
43+
```
44+
45+
### Database Setup
46+
The plugin uses Liquibase for database migrations. Scripts are located in `src/main/resources/db/changelog/`.
47+
48+
### Running the Plugin
49+
This is a library/plugin that extends Apache Fineract. It runs as part of the Fineract application, not as a standalone service.
50+
51+
#### Deployment Options:
52+
```bash
53+
# With Apache Fineract (Docker)
54+
java -Dloader.path=$PLUGIN_HOME/libs/ -jar fineract-provider.jar
55+
56+
# With Apache Fineract (Tomcat)
57+
Copy JAR to $TOMCAT_HOME/webapps/fineract-provider/WEB-INF/lib/
58+
```
59+
60+
## Coding Standards
61+
62+
### File Structure
63+
```text
64+
src/main/java/org/apache/fineract/selfservice/
65+
- security/ # Authentication and authorization
66+
- useradministration/ # User management
67+
- client/ # Client operations
68+
- savings/ # Savings account operations
69+
- loanaccount/ # Loan account operations
70+
- products/ # Product browsing
71+
- registration/ # User registration
72+
- config/ # Configuration classes
73+
```
74+
75+
### Code Style
76+
- Follow Google Java Format (enforced by Spotless Maven plugin)
77+
- Use Lombok for boilerplate reduction
78+
- RequiredArgsConstructor for dependency injection
79+
- Proper Javadoc for public APIs
80+
81+
### Security Guidelines
82+
- All endpoints must be secured with appropriate permissions
83+
- Use `@PreAuthorize` annotations for method-level security
84+
- Validate all input data using DataValidators
85+
- Never expose sensitive information in API responses
86+
87+
### API Design
88+
- Use JAX-RS annotations (`@Path`, `@GET`, `@POST`, etc.)
89+
- Return proper HTTP status codes
90+
- Use OpenAPI tags for documentation
91+
- Follow RESTful conventions
92+
93+
### Testing
94+
- Unit tests for all service classes
95+
- Integration tests for API endpoints
96+
- Use TestContainers for database tests
97+
- Mock external dependencies
98+
99+
## Common Patterns
100+
101+
### Service Layer
102+
```java
103+
@Service
104+
@RequiredArgsConstructor
105+
public class ExampleServiceImpl implements ExampleService {
106+
private final ExampleRepository repository;
107+
108+
@Override
109+
@Transactional
110+
public Result performOperation(Command command) {
111+
// Implementation
112+
}
113+
}
114+
```
115+
116+
### API Resource
117+
```java
118+
@Path("/v1/self/example")
119+
@Component
120+
@Tag(name = "Self Example", description = "Example operations")
121+
@RequiredArgsConstructor
122+
public class SelfExampleApiResource {
123+
private final ExampleService service;
124+
125+
@GET
126+
@Path("/{id}")
127+
public Response getExample(@PathParam("id") Long id) {
128+
// Implementation
129+
}
130+
}
131+
```
132+
133+
### Data Validation
134+
```java
135+
@Component
136+
public class ExampleDataValidator {
137+
private final FromJsonHelper fromJsonHelper;
138+
139+
public void validate(String json) {
140+
// Validation logic
141+
}
142+
}
143+
```
144+
145+
## Important Notes
146+
147+
- This is a plugin, not a standalone application
148+
- Depends on Apache Fineract core modules
149+
- Uses multi-tenant architecture
150+
- Security is critical - handle with care
151+
- Follow Fineract coding conventions
152+
153+
## Debugging Tips
154+
155+
- Enable debug logging: `logging.level.org.apache.fineract.selfservice=DEBUG`
156+
- Use Spring Boot Actuator endpoints for monitoring
157+
- Check application logs for security-related issues
158+
- Verify database migrations in development
159+
160+
## References
161+
162+
- [Apache Fineract Documentation](https://fineract.apache.org/)
163+
- [Spring Boot Documentation](https://spring.io/projects/spring-boot)
164+
- [JAX-RS Specification](https://jakarta.ee/specifications/restful-ws/)
165+
- [Spring Security Reference](https://spring.io/projects/spring-security)
166+
167+
## Contact
168+
169+
For questions about this repository:
170+
- Create an issue on GitHub
171+
- Check the Mifos community forums
172+
- Review existing documentation and code comments

0 commit comments

Comments
 (0)