javi-forge 1.2.0 → 1.3.0

package/ai-config/skills/database/graph-databases/SKILL.md

@@ -1,218 +0,0 @@
----
-name: graph-databases
-description: >
-  Graph database concepts. Nodes, relationships, traversals, Cypher/Gremlin queries.
-  Trigger: graph database, Neo4j, Neptune, ArangoDB, nodes, relationships, Cypher
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [graph, database, neo4j, neptune]
-  scope: ["**/graph/**"]
----
-
-# Graph Database Concepts
-
-## Core Concepts
-
-```
-Nodes: Entities (vertices)
-- User, Product, Order
-- Have properties (key-value)
-- Have labels (types)
-
-Relationships: Connections (edges)
-- FOLLOWS, PURCHASED, KNOWS
-- Have direction (or bidirectional)
-- Have properties (weight, timestamp)
-
-Properties: Key-value attributes
-- On nodes: name, email, created_at
-- On relationships: since, strength, role
-```
-
-## When to Use Graph Databases
-
-```
-Good fit:
-✅ Social networks (friends, followers)
-✅ Recommendation engines
-✅ Fraud detection (pattern matching)
-✅ Knowledge graphs
-✅ Network topology
-✅ Access control (who can see what)
-
-Poor fit:
-❌ Simple CRUD operations
-❌ High-volume transactions
-❌ Full-text search (use Elasticsearch)
-❌ Time-series data
-❌ Large binary storage
-```
-
-## Graph vs Relational
-
-```
-Relational (SQL):
-┌─────────┐      ┌────────────────┐      ┌─────────┐
-│ users   │──────│ friendships    │──────│ users   │
-│ id=1    │      │ user_id=1      │      │ id=2    │
-│ name=A  │      │ friend_id=2    │      │ name=B  │
-└─────────┘      └────────────────┘      └─────────┘
-
-Graph:
-   ┌──────────┐  FOLLOWS   ┌──────────┐
-   │  (User)  │───────────▶│  (User)  │
-   │ name: A  │            │ name: B  │
-   └──────────┘            └──────────┘
-
-SQL for "friends of friends":
-SELECT DISTINCT u3.name FROM users u1
-JOIN friendships f1 ON u1.id = f1.user_id
-JOIN friendships f2 ON f1.friend_id = f2.user_id
-JOIN users u3 ON f2.friend_id = u3.id
-WHERE u1.id = 1 AND u3.id != 1
--- Becomes complex for N levels
-
-Cypher (Neo4j):
-MATCH (u:User {id: 1})-[:FOLLOWS*2]->(fof:User)
-WHERE fof <> u
-RETURN DISTINCT fof.name
--- Same query, any depth with *N
-```
-
-## Cypher Query Language (Neo4j)
-
-### Basic Patterns
-```cypher
-// Create nodes
-CREATE (u:User {name: 'Alice', email: 'alice@example.com'})
-
-// Create relationship
-MATCH (a:User {name: 'Alice'}), (b:User {name: 'Bob'})
-CREATE (a)-[:FOLLOWS {since: date()}]->(b)
-
-// Find nodes
-MATCH (u:User {name: 'Alice'})
-RETURN u
-
-// Find relationships
-MATCH (a:User)-[r:FOLLOWS]->(b:User)
-RETURN a.name, r.since, b.name
-
-// Traversal
-MATCH (u:User {name: 'Alice'})-[:FOLLOWS*1..3]->(friend)
-RETURN DISTINCT friend.name
-```
-
-### Advanced Queries
-```cypher
-// Shortest path
-MATCH path = shortestPath(
-  (a:User {name: 'Alice'})-[:FOLLOWS*]-(b:User {name: 'Zara'})
-)
-RETURN path
-
-// Aggregation
-MATCH (u:User)-[:FOLLOWS]->(follower)
-RETURN u.name, count(follower) AS followers
-ORDER BY followers DESC
-LIMIT 10
-
-// Pattern matching (fraud detection)
-MATCH (a:Account)-[:TRANSFER]->(b:Account)-[:TRANSFER]->(c:Account)-[:TRANSFER]->(a)
-WHERE a.suspicious = true
-RETURN a, b, c
-```
-
-## Gremlin Query Language (Neptune, JanusGraph)
-
-```groovy
-// Create vertex
-g.addV('User').property('name', 'Alice')
-
-// Create edge
-g.V().has('User', 'name', 'Alice')
-  .addE('FOLLOWS').to(g.V().has('User', 'name', 'Bob'))
-
-// Traversal
-g.V().has('User', 'name', 'Alice')
-  .out('FOLLOWS')
-  .out('FOLLOWS')
-  .dedup()
-  .values('name')
-
-// Shortest path
-g.V().has('User', 'name', 'Alice')
-  .repeat(out('FOLLOWS').simplePath())
-  .until(has('User', 'name', 'Zara'))
-  .path()
-  .limit(1)
-```
-
-## Data Modeling Patterns
-
-### Social Network
-```
-(:User)-[:FOLLOWS]->(:User)
-(:User)-[:POSTED]->(:Post)
-(:User)-[:LIKES]->(:Post)
-(:Post)-[:TAGGED]->(:Topic)
-```
-
-### E-commerce Recommendations
-```
-(:Customer)-[:PURCHASED]->(:Product)
-(:Product)-[:IN_CATEGORY]->(:Category)
-(:Customer)-[:VIEWED]->(:Product)
-(:Product)-[:SIMILAR_TO]->(:Product)
-```
-
-### Access Control
-```
-(:User)-[:MEMBER_OF]->(:Group)
-(:Group)-[:HAS_ROLE]->(:Role)
-(:Role)-[:CAN_ACCESS]->(:Resource)
-```
-
-## Performance Considerations
-
-```
-Indexing:
-- Index frequently queried properties
-- Composite indexes for common patterns
-- Full-text indexes for search
-
-Query optimization:
-- Start traversals from selective nodes
-- Limit traversal depth
-- Use PROFILE to analyze queries
-
-Cardinality:
-- Avoid super nodes (millions of edges)
-- Consider edge partitioning
-- Use intermediate nodes for many-to-many
-```
-
-## Graph Database Comparison
-
-```
-| Feature | Neo4j | Neptune | ArangoDB |
-|---------|-------|---------|----------|
-| Query | Cypher | Gremlin | AQL |
-| Model | LPG | LPG/RDF | Multi-model |
-| Scaling | Read replicas | Auto-scaling | Sharding |
-| Hosting | Self/Cloud | AWS only | Self/Cloud |
-| ACID | Yes | Yes | Yes |
-```
-
-## Related Skills
-
-- `graph-spring`: Spring Boot graph implementation
-- `apigen-architecture`: Overall system architecture
-
-

package/ai-config/skills/database/graph-spring/SKILL.md

@@ -1,361 +0,0 @@
----
-name: graph-spring
-description: >
-  Spring Boot graph database integration. Neo4j, Neptune, ArangoDB with Spring Data.
-  Trigger: apigen-graph, Neo4jRepository, GraphService, Spring Data Neo4j
-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [graph, spring-boot, neo4j, java]
-  scope: ["apigen-graph/**"]
----
-
-# Graph Spring Boot (apigen-graph)
-
-## Configuration
-
-```yaml
-apigen:
-  graph:
-    enabled: true
-    provider: neo4j  # neo4j, neptune, arangodb
-
-    neo4j:
-      uri: bolt://localhost:7687
-      username: neo4j
-      password: ${NEO4J_PASSWORD}
-      database: neo4j
-      connection-pool-size: 50
-
-    neptune:
-      endpoint: ${NEPTUNE_ENDPOINT}
-      port: 8182
-      region: us-east-1
-      iam-auth: true
-
-    arangodb:
-      host: localhost
-      port: 8529
-      database: apigen
-      username: root
-      password: ${ARANGO_PASSWORD}
-```
-
-## Neo4j Entity Mapping
-
-```java
-@Node("User")
-public class UserNode {
-
-    @Id
-    @GeneratedValue
-    private Long id;
-
-    @Property("externalId")
-    private UUID externalId;
-
-    private String name;
-    private String email;
-    private Instant createdAt;
-
-    @Relationship(type = "FOLLOWS", direction = Direction.OUTGOING)
-    private Set<UserNode> following = new HashSet<>();
-
-    @Relationship(type = "FOLLOWS", direction = Direction.INCOMING)
-    private Set<UserNode> followers = new HashSet<>();
-
-    @Relationship(type = "PURCHASED")
-    private List<PurchaseRelationship> purchases = new ArrayList<>();
-}
-
-@RelationshipProperties
-public class PurchaseRelationship {
-
-    @Id
-    @GeneratedValue
-    private Long id;
-
-    @TargetNode
-    private ProductNode product;
-
-    private Instant purchasedAt;
-    private BigDecimal amount;
-    private Integer quantity;
-}
-
-@Node("Product")
-public class ProductNode {
-    @Id @GeneratedValue
-    private Long id;
-
-    private String sku;
-    private String name;
-    private String category;
-
-    @Relationship(type = "SIMILAR_TO")
-    private List<ProductNode> similarProducts;
-}
-```
-
-## Repository Layer
-
-```java
-public interface UserNodeRepository extends Neo4jRepository<UserNode, Long> {
-
-    Optional<UserNode> findByExternalId(UUID externalId);
-
-    @Query("MATCH (u:User {externalId: $userId})-[:FOLLOWS]->(f:User) RETURN f")
-    List<UserNode> findFollowing(UUID userId);
-
-    @Query("MATCH (u:User {externalId: $userId})<-[:FOLLOWS]-(f:User) RETURN f")
-    List<UserNode> findFollowers(UUID userId);
-
-    @Query("""
-        MATCH (u:User {externalId: $userId})-[:FOLLOWS*2]->(fof:User)
-        WHERE fof.externalId <> $userId
-        RETURN DISTINCT fof
-        LIMIT $limit
-        """)
-    List<UserNode> findFriendsOfFriends(UUID userId, int limit);
-
-    @Query("""
-        MATCH path = shortestPath(
-          (a:User {externalId: $fromId})-[:FOLLOWS*1..6]-(b:User {externalId: $toId})
-        )
-        RETURN path
-        """)
-    List<UserNode> findShortestPath(UUID fromId, UUID toId);
-}
-```
-
-## Graph Service
-
-```java
-@Service
-@RequiredArgsConstructor
-public class GraphService {
-
-    private final UserNodeRepository userRepository;
-    private final ProductNodeRepository productRepository;
-    private final Neo4jClient neo4jClient;
-
-    @Transactional
-    public void createFollowRelationship(UUID followerId, UUID followeeId) {
-        UserNode follower = userRepository.findByExternalId(followerId)
-            .orElseThrow(() -> new NodeNotFoundException("User", followerId));
-        UserNode followee = userRepository.findByExternalId(followeeId)
-            .orElseThrow(() -> new NodeNotFoundException("User", followeeId));
-
-        follower.getFollowing().add(followee);
-        userRepository.save(follower);
-    }
-
-    @Transactional(readOnly = true)
-    public List<UserDTO> getRecommendedConnections(UUID userId, int limit) {
-        // Friends of friends who aren't already friends
-        return neo4jClient.query("""
-            MATCH (u:User {externalId: $userId})-[:FOLLOWS]->()-[:FOLLOWS]->(rec:User)
-            WHERE NOT (u)-[:FOLLOWS]->(rec) AND rec <> u
-            WITH rec, count(*) as mutualFriends
-            ORDER BY mutualFriends DESC
-            LIMIT $limit
-            RETURN rec, mutualFriends
-            """)
-            .bind(userId).to("userId")
-            .bind(limit).to("limit")
-            .fetchAs(UserDTO.class)
-            .mappedBy((typeSystem, record) -> new UserDTO(
-                record.get("rec").get("externalId").asString(),
-                record.get("rec").get("name").asString(),
-                record.get("mutualFriends").asInt()
-            ))
-            .all();
-    }
-
-    @Transactional(readOnly = true)
-    public List<ProductNode> getProductRecommendations(UUID userId, int limit) {
-        // Products purchased by users who purchased similar products
-        return neo4jClient.query("""
-            MATCH (u:User {externalId: $userId})-[:PURCHASED]->(p:Product)
-                  <-[:PURCHASED]-(other:User)-[:PURCHASED]->(rec:Product)
-            WHERE NOT (u)-[:PURCHASED]->(rec)
-            WITH rec, count(DISTINCT other) as score
-            ORDER BY score DESC
-            LIMIT $limit
-            RETURN rec
-            """)
-            .bind(userId).to("userId")
-            .bind(limit).to("limit")
-            .fetchAs(ProductNode.class)
-            .all();
-    }
-}
-```
-
-## Neptune Integration (AWS)
-
-```java
-@Configuration
-@ConditionalOnProperty(prefix = "apigen.graph", name = "provider", havingValue = "neptune")
-public class NeptuneConfiguration {
-
-    @Bean
-    public Cluster neptuneCluster(GraphProperties props) {
-        return Cluster.build()
-            .addContactPoint(props.getNeptune().getEndpoint())
-            .port(props.getNeptune().getPort())
-            .enableSsl(true)
-            .channelizer(SigV4WebSocketChannelizer.class)
-            .create();
-    }
-
-    @Bean
-    public GraphTraversalSource g(Cluster cluster) {
-        return AnonymousTraversalSource.traversal()
-            .withRemote(DriverRemoteConnection.using(cluster));
-    }
-}
-
-@Service
-@ConditionalOnProperty(prefix = "apigen.graph", name = "provider", havingValue = "neptune")
-public class NeptuneGraphService {
-
-    private final GraphTraversalSource g;
-
-    public List<Map<String, Object>> findFriendsOfFriends(String userId) {
-        return g.V().has("User", "userId", userId)
-            .out("FOLLOWS")
-            .out("FOLLOWS")
-            .dedup()
-            .hasNot("userId", userId)
-            .valueMap("userId", "name")
-            .toList();
-    }
-}
-```
-
-## ArangoDB Integration
-
-```java
-@Configuration
-@ConditionalOnProperty(prefix = "apigen.graph", name = "provider", havingValue = "arangodb")
-public class ArangoConfiguration {
-
-    @Bean
-    public ArangoDB arangoDB(GraphProperties props) {
-        return new ArangoDB.Builder()
-            .host(props.getArangodb().getHost(), props.getArangodb().getPort())
-            .user(props.getArangodb().getUsername())
-            .password(props.getArangodb().getPassword())
-            .build();
-    }
-
-    @Bean
-    public ArangoDatabase database(ArangoDB arangoDB, GraphProperties props) {
-        return arangoDB.db(props.getArangodb().getDatabase());
-    }
-}
-
-@Repository
-@ConditionalOnProperty(prefix = "apigen.graph", name = "provider", havingValue = "arangodb")
-public class ArangoUserRepository {
-
-    private final ArangoDatabase db;
-
-    public List<UserDTO> findFriendsOfFriends(String userId) {
-        String aql = """
-            FOR u IN users
-              FILTER u._key == @userId
-              FOR fof IN 2..2 OUTBOUND u follows
-                FILTER fof._key != @userId
-                COLLECT user = fof WITH COUNT INTO cnt
-                SORT cnt DESC
-                RETURN {user: user, mutualFriends: cnt}
-            """;
-
-        return db.query(aql, Map.of("userId", userId), UserDTO.class)
-            .asListRemaining();
-    }
-}
-```
-
-## Graph Auto Configuration
-
-```java
-@AutoConfiguration
-@ConditionalOnProperty(prefix = "apigen.graph", name = "enabled", havingValue = "true")
-@EnableConfigurationProperties(GraphProperties.class)
-public class GraphAutoConfiguration {
-
-    @Bean
-    @ConditionalOnProperty(prefix = "apigen.graph", name = "provider", havingValue = "neo4j")
-    public Neo4jClient neo4jClient(Driver driver) {
-        return Neo4jClient.create(driver);
-    }
-
-    @Bean
-    @ConditionalOnMissingBean
-    public GraphService graphService(
-            @Autowired(required = false) UserNodeRepository neo4jRepo,
-            @Autowired(required = false) NeptuneGraphService neptuneService,
-            @Autowired(required = false) ArangoUserRepository arangoRepo) {
-        // Factory based on available beans
-    }
-}
-```
-
-## Testing with TestContainers
-
-```java
-@SpringBootTest
-@Testcontainers
-class GraphServiceIT {
-
-    @Container
-    @ServiceConnection
-    static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5")
-        .withAdminPassword("password");
-
-    @Autowired
-    private GraphService graphService;
-
-    @Autowired
-    private UserNodeRepository userRepository;
-
-    @BeforeEach
-    void setUp() {
-        userRepository.deleteAll();
-    }
-
-    @Test
-    void shouldFindFriendsOfFriends() {
-        // Create graph: Alice -> Bob -> Charlie
-        UserNode alice = userRepository.save(new UserNode("Alice"));
-        UserNode bob = userRepository.save(new UserNode("Bob"));
-        UserNode charlie = userRepository.save(new UserNode("Charlie"));
-
-        graphService.createFollowRelationship(alice.getExternalId(), bob.getExternalId());
-        graphService.createFollowRelationship(bob.getExternalId(), charlie.getExternalId());
-
-        List<UserNode> fof = userRepository.findFriendsOfFriends(
-            alice.getExternalId(), 10);
-
-        assertThat(fof).hasSize(1);
-        assertThat(fof.get(0).getName()).isEqualTo("Charlie");
-    }
-}
-```
-
-## Related Skills
-
-- `graph-databases`: Graph database concepts
-- `spring-boot-4`: Spring Boot 4.0 patterns
-- `testcontainers`: Integration testing
-
-