Kor.ai Contributor Guide - ravkorsurv/kor-ai-core GitHub Wiki

Kor.ai Contributor Guide

1. Overview

Kor.ai is a modular, cloud-native surveillance platform targeting market abuse detection using probabilistic (Bayesian) logic. The goal is to build an explainable, scalable system that works across multiple risk typologies starting with insider dealing and spoofing. All components are designed for zero-maintenance and auto-deployment.

2. Engagement Model

  • Repos:
    • kor-ai-core: backend, Bayesian models, infra, testing
    • kor-ai-alert-ui: frontend (Vite + React)
  • Source of Truth: GitHub Wiki in kor-ai-core
  • ChatGPT role: Co-developer, architect, and documenter
  • Branches:
    • main: stable deployments
    • dev: active development
    • feature/*: one per feature or fix
  • Work Tracking:
    • Use GitHub Issues and Projects
    • Document and link work in PRs

3. Development Lifecycle

  1. Raise issue or request in GitHub or ChatGPT
  2. Design discussion in ChatGPT (copy to Wiki if needed)
  3. Code in feature/* branch
  4. Add tests and documentation
  5. Create PR → review → merge to main
  6. CI/CD auto-deploys to AWS (Amplify / Lambda)
  7. Update Wiki with changes

4. Folder Structure (Core)

kor-ai-core/ │ ├── bayesian-models/ │ ├── components/ # Node modules (e.g. Q1.json) │ ├── models/ # Full models (e.g. InsiderModel.json) │ └── payloads/ # Test inputs (e.g. spoofing_case_medium.json) │ ├── api/ # Python or Node APIs ├── infra/ # CDK, Terraform scripts ├── tests/ # pytest/unit/integration ├── docs/ # Visuals, diagrams, notes

5. Testing & Validation

  • Tools: pytest, unittest, vitest, jest
  • Test Levels:
    • Unit tests for all functions
    • Integration tests for API and Agena calls
    • Validation: risk scores checked against mock scenarios
  • CI/CD: GitHub Actions
    • Auto-deploys main to AWS Amplify
    • Test coverage required before merge

6. Documentation Rules

  • Wiki pages per feature/module
  • Markdown only — clear, concise, versioned
  • Commit messages:
    • Format: type(scope): message
    • Examples: feat(api): add risk score endpoint
  • Every PR must include:
    • Code change
    • Wiki/docs update
    • Test cases (mock or real)

7. Alert Metadata Glossary

  • riskScore: Bayesian risk probability (0–100%)
  • status: Open, In Review, Closed, Dismissed
  • assignedTo: L1/L2/L3 analyst ID
  • caseAge: Days since opened

8. Versioning & Releases

  • Follow SemVer (v0.1.0, v1.0.0)
  • Weekly changelog in Wiki
  • Tag each release with scope description

9. Secrets & Access

  • Local dev secrets in .env (never committed)
  • Production secrets via AWS Secrets Manager
  • Access managed via AWS IAM Identity Center

Let this document serve as the operating manual for current and future contributors. Update regularly as the project evolves.