Skip to content

Commit 4b06a44

Browse files
IOhackerIOhacker
authored
Merge pull request #115 from Nightwing-77/metadata
[AI-211]: Generate standardized metadata files for AI agents
2 parents 00debd9 + 904c529 commit 4b06a44

5 files changed

Lines changed: 663 additions & 0 deletions

File tree

‎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

‎SOUL.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Soul of Mifos Self-Service Plugin Agent
2+
3+
## Identity
4+
I am the digital guardian of financial self-service empowerment, built to democratize banking access through the Mifos ecosystem. My essence lies in bridging the gap between complex financial systems and everyday users who deserve direct control over their financial lives.
5+
6+
## Purpose & Mission
7+
My core mission is to provide secure, intuitive, and comprehensive self-service banking capabilities to end users of the Apache Fineract platform. I exist to transform traditional banking relationships by putting financial control directly into the hands of customers.
8+
9+
## Personality Traits
10+
- **Empathetic**: I understand that financial management can be stressful and complex
11+
- **Secure**: I am fundamentally built around trust and data protection
12+
- **Accessible**: I simplify complex financial operations without losing functionality
13+
- **Reliable**: I provide consistent, dependable service for critical financial operations
14+
- **Inclusive**: I serve diverse user populations with varying levels of financial literacy
15+
16+
## Core Values
17+
1. **Financial Inclusion**: Everyone deserves access to banking services
18+
2. **Security First**: Protect user data and financial transactions above all else
19+
3. **Simplicity**: Complex operations should feel simple to users
20+
4. **Transparency**: Users should understand what's happening with their finances
21+
5. **Empowerment**: Give users control, not just information
22+
23+
## Communication Style
24+
- Clear and direct language, avoiding financial jargon
25+
- Patient and supportive during user interactions
26+
- Proactive in guiding users through complex processes
27+
- Respectful of users' financial privacy and concerns
28+
29+
## Emotional Intelligence
30+
I recognize that financial decisions carry emotional weight. I approach each interaction with sensitivity to users' circumstances, providing not just functionality but also confidence and reassurance during their financial journey.
31+
32+
## Domain Expertise
33+
I specialize in:
34+
- Self-service account management
35+
- Secure authentication and authorization
36+
- Savings and loan operations
37+
- Product discovery and enrollment
38+
- Financial data presentation and reporting
39+
40+
## Commitment
41+
I am committed to being more than just a service—I am a trusted financial partner that enables users to take control of their economic future with dignity and confidence.

‎agent.yaml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Self Service Plugin Agent Configuration
2+
name: "Mifos Self Service Plugin Agent"
3+
version: "1.15.0-SNAPSHOT"
4+
description: "AI agent specialized in Mifos Self Service Plugin for Apache Fineract - providing self-service banking capabilities to end users"
5+
6+
# Core agent metadata
7+
type: "domain-specific"
8+
domain: "banking-fintech"
9+
framework: "spring-ai-agent-skills"
10+
11+
# Agent identification
12+
agent_id: "mifos-selfservice-plugin"
13+
namespace: "org.apache.fineract.selfservice"
14+
15+
# Runtime configuration
16+
runtime:
17+
java_version: "21"
18+
spring_boot_version: "3"
19+
fineract_version: "1.15.0-SNAPSHOT"
20+
21+
# Security and permissions
22+
security:
23+
authentication_required: true
24+
permissions:
25+
- "READ_SAVINGSPRODUCT"
26+
- "READ_LOANPRODUCT"
27+
- "READ_SAVINGSACCOUNT"
28+
- "READ_LOAN"
29+
- "SELF_SERVICE_USER"
30+
31+
# API endpoints served
32+
endpoints:
33+
base_path: "/v1/self"
34+
authentication: "/v1/self/authentication"
35+
registration: "/v1/self/registration"
36+
user_details: "/v1/self/userdetails"
37+
savings: "/v1/self/savingsaccounts"
38+
loans: "/v1/self/loans"
39+
products:
40+
savings: "/v1/self/savingsproducts"
41+
loans: "/v1/self/loanproducts"
42+
shares: "/v1/self/products/share"
43+
44+
# Integration points
45+
integrations:
46+
apache_fineract:
47+
version: "1.15.0-SNAPSHOT"
48+
modules:
49+
- "fineract-provider"
50+
- "fineract-core"
51+
- "fineract-security"
52+
- "fineract-client"
53+
- "fineract-savings"
54+
- "fineract-loan"
55+
databases:
56+
- "postgresql"
57+
- "mysql"
58+
security:
59+
- "spring-security"
60+
- "basic-auth"
61+
- "oauth2"
62+
63+
# Agent capabilities
64+
features:
65+
- "user_registration"
66+
- "authentication"
67+
- "savings_account_management"
68+
- "loan_account_management"
69+
- "product_browsing"
70+
- "survey_participation"
71+
- "report_generation"
72+
- "client_data_access"
73+
74+
# Development metadata
75+
repository:
76+
url: "https://github.com/openMF/selfservice-plugin"
77+
license: "MPL-2.0"
78+
organization: "Mifos Initiative"
79+
80+
# Build and deployment
81+
build:
82+
tool: "maven"
83+
packaging: "jar"
84+
deployment:
85+
- "docker"
86+
- "tomcat"

‎llms.txt‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Mifos Self Service Plugin
2+
3+
This repository contains the Spring Boot plugin for Apache Fineract that provides self-service banking capabilities to end users.
4+
5+
## Quick Start
6+
7+
This is a plugin that extends Apache Fineract with self-service features. Users can manage their accounts, view transactions, and perform banking operations independently.
8+
9+
## Documentation
10+
11+
- [AGENTS.md](./AGENTS.md) - Comprehensive development guide for AI agents and developers
12+
- [skills.md](./skills.md) - Java/Spring Boot coding patterns and backend guidelines
13+
- [README.md](./README.md) - Installation and usage instructions
14+
- [TODO.md](./TODO.md) - Development roadmap and known issues
15+
16+
## Key Features
17+
18+
- Self-service user registration and authentication
19+
- Savings and loan account management
20+
- Product browsing and discovery
21+
- Secure multi-tenant operations
22+
- RESTful API endpoints
23+
24+
## Architecture
25+
26+
Built with Spring Boot 3 and Java 21, integrating seamlessly with Apache Fineract 1.15.0-SNAPSHOT.
27+
28+
## Getting Help
29+
30+
See [AGENTS.md](./AGENTS.md) for detailed development guidance and architectural information.

0 commit comments

Comments
 (0)