{"id":50325957,"url":"https://github.com/imajkumar/casbytes","last_synced_at":"2026-05-29T06:03:31.024Z","repository":{"id":358152031,"uuid":"1240029587","full_name":"imajkumar/casbytes","owner":"imajkumar","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-15T23:42:41.000Z","size":109,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T02:17:13.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imajkumar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T17:37:43.000Z","updated_at":"2026-05-15T23:42:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/imajkumar/casbytes","commit_stats":null,"previous_names":["imajkumar/casbytes"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/imajkumar/casbytes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imajkumar%2Fcasbytes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imajkumar%2Fcasbytes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imajkumar%2Fcasbytes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imajkumar%2Fcasbytes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imajkumar","download_url":"https://codeload.github.com/imajkumar/casbytes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imajkumar%2Fcasbytes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33639056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T06:03:30.091Z","updated_at":"2026-05-29T06:03:31.018Z","avatar_url":"https://github.com/imajkumar.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CasBytes Core Service\n\nEnterprise foundation for the **CasBytes** ERP SaaS platform. This repository is the **Core** service (`casbytes-core-service`), designed as a modular monolith today and as a **microservice-ready** domain boundary tomorrow.\n\n- **Company:** CasBytes — https://casbytes.com  \n- **Maven coordinates:** `com.casbytes:casbytes-core-service`  \n- **Default database:** `casbytes_core_db` (PostgreSQL, schema `public`)\n\n## Mandatory onboarding\n\nBefore writing production code, read:\n\n1. `docs/ONBOARDING.md` (**required**)\n2. `docs/CODING_STANDARDS.md`\n3. `docs/ARCHITECTURE.md`\n4. `docs/GIT_CONVENTIONS.md`\n5. `docs/PRODUCTION_BEST_PRACTICES.md`\n6. `docs/OAUTH2_AND_CASBIN.md` (OAuth2 RS, Casbin JDBC, Testcontainers)\n\n## Technology stack\n\n| Area | Choice |\n|------|--------|\n| Runtime | Java **21** (LTS), Spring Boot **4.0.x** |\n| API | Spring Web MVC, Bean Validation, OpenAPI (springdoc **3.x**) |\n| Persistence | Spring Data JPA, Hibernate, Flyway |\n| Cache | Spring Data Redis |\n| Messaging | Spring for Apache Kafka |\n| Security | Spring Security (stateless), JWT hooks (future Auth service) |\n| Authorization | Casbin (`jcasbin`) with classpath bootstrap policy |\n| Observability | Actuator, Micrometer Prometheus, structured logging (Logback), correlation IDs |\n| Mapping | MapStruct |\n\n\u003e **Note:** Spring Boot 4 uses **Jackson 3** (`tools.jackson.*`) for the HTTP JSON mapper. Example customization lives in `JacksonConfiguration`.\n\n## Configuration model (no `.env` files)\n\nConfiguration is **YAML + Spring profiles** plus **OS environment variables** / Kubernetes secrets.  \n**Never commit secrets** (passwords, private keys, tokens). Use placeholders such as `${CASBYTES_DATASOURCE_PASSWORD:}` and inject values via your shell, systemd, Docker, or Kubernetes.\n\nExample local PostgreSQL URL (matches your target topology):\n\n`jdbc:postgresql://localhost:5432/casbytes_core_db?currentSchema=public` (or `localhost:5433` when using the bundled `docker-compose.yml`, which maps Postgres to **5433** to avoid clashes with a system install).\n\nSet credentials in the environment (example for interactive dev shells only):\n\n```bash\nexport CASBYTES_DATASOURCE_USERNAME=\"ayra\"\nexport CASBYTES_DATASOURCE_PASSWORD='(set locally; do not commit)'\n```\n\n## Spring profiles\n\n| Profile | Purpose |\n|---------|---------|\n| `dev` | Local developer workstation; verbose SQL logging; `casbytes.security.permit-api-without-auth=true` |\n| `stage` | Pre-production integration; closer to prod defaults |\n| `prod` | Production hardening; Swagger UI disabled |\n| `test` | Unit/integration tests (H2, Kafka/Redis infra disabled) |\n\n### Sample startup commands\n\nSee **Major commands** for the full list. Common shortcuts:\n\n```bash\n# Local development (PostgreSQL + Redis + Kafka must match application-dev overrides)\n./mvnw spring-boot:run -Dspring-boot.run.profiles=dev\n\n# Explicit JVM + profile (typical in servers)\njava -jar target/casbytes-core-service-0.1.0-SNAPSHOT.jar --spring.profiles.active=stage\n\n# Production-style jar run\njava -XX:MaxRAMPercentage=75.0 -jar target/casbytes-core-service-0.1.0-SNAPSHOT.jar --spring.profiles.active=prod\n```\n\n## API versioning\n\n- **URI versioning:** all first-party REST APIs live under `/api/v1/...`\n- Add `/api/v2` when breaking changes are introduced; keep v1 until consumers migrate.\n\n## Standard HTTP response envelope\n\n### Success\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n    \"code\": \"DEMO-001\",\n    \"name\": \"Demo reference item\",\n    \"active\": true,\n    \"createdAt\": \"2026-05-15T10:15:30Z\",\n    \"updatedAt\": \"2026-05-15T10:15:30Z\"\n  },\n  \"error\": null,\n  \"meta\": {\n    \"timestamp\": \"2026-05-15T10:15:30.123Z\",\n    \"correlationId\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"path\": \"/api/v1/reference/items/3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  }\n}\n```\n\n### Error\n\n```json\n{\n  \"success\": false,\n  \"data\": null,\n  \"error\": {\n    \"code\": \"VALIDATION_FAILED\",\n    \"message\": \"Validation failed\",\n    \"details\": [\n      {\n        \"field\": \"code\",\n        \"message\": \"must not be blank\",\n        \"rejectedValue\": \"\"\n      }\n    ],\n    \"traceId\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"path\": \"/api/v1/reference/items\"\n  },\n  \"meta\": {\n    \"timestamp\": \"2026-05-15T10:15:30.456Z\",\n    \"correlationId\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"path\": \"/api/v1/reference/items\"\n  }\n}\n```\n\n## Enterprise health endpoints (application API)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/v1/health` | Aggregated checks (database, redis, kafka) |\n| `GET` | `/api/v1/health/db` | Database probe (`SELECT 1`) |\n| `GET` | `/api/v1/health/redis` | Redis `PING` (or `SKIPPED` if Redis is not configured) |\n| `GET` | `/api/v1/health/kafka` | Kafka cluster metadata probe (or `SKIPPED` if disabled) |\n\nKubernetes **liveness/readiness** should still prefer Spring Boot Actuator (`/actuator/health`) on the **management port** (`8081` by default) for standard probes.\n\n## Actuator \u0026 management port\n\n- **Application port:** `8080` (`server.port`)\n- **Management port:** `8081` (`management.server.port`)\n\nExposed actuator web endpoints (base path `/actuator`): `health`, `info`, `prometheus`, `metrics`, `loggers` (tune per environment).\n\n## OpenAPI / Swagger UI\n\n- **OpenAPI JSON:** `/v3/api-docs`\n- **Swagger UI:** `/swagger-ui.html` (springdoc 3 defaults)\n\nProduction profile disables springdoc by default.\n\n## Request tracing\n\n- Incoming header: `X-Correlation-Id` (fallback: `X-Trace-Id`)\n- Response echoes the same headers.\n- Logback pattern includes MDC `correlationId`.\n\n## Docker\n\n```bash\n./mvnw -DskipTests package\ndocker build -t casbytes/core-service:dev .\n```\n\n`docker-compose.yml` starts **PostgreSQL**, **Redis**, **Apache Zookeeper**, **Apache Kafka** (Confluent Community images), **[Kafka UI](https://github.com/kafbat/kafka-ui)**, **Elasticsearch**, and **Kibana** for local development. Export `CASBYTES_DATASOURCE_PASSWORD` before `docker compose up` (the compose file intentionally requires it).\n\n**Published host ports (defaults avoid common local installs):** Postgres **5433**→5432, Redis **6380**→6379, Zookeeper **2182**→2181, Kafka **9094**→9094 (`PLAINTEXT_HOST` for apps on the host), **Kafka UI** **8099**→8080 (`http://localhost:8099`), **Elasticsearch** **9201**→9200 (`http://localhost:9201`), **Kibana** **5602**→5601 (`http://localhost:5602`). Override with `CASBYTES_COMPOSE_POSTGRES_PORT`, `CASBYTES_COMPOSE_REDIS_PORT`, `CASBYTES_COMPOSE_ZOOKEEPER_PORT`, `CASBYTES_COMPOSE_KAFKA_HOST_PORT`, `CASBYTES_COMPOSE_KAFKA_UI_PORT`, `CASBYTES_COMPOSE_ELASTICSEARCH_PORT`, `CASBYTES_COMPOSE_KIBANA_PORT` if needed. The `dev` Spring profile (`application-dev.yml`) lines up JDBC, Redis, Kafka bootstrap, and Elasticsearch with these defaults.\n\n## Project structure (high level)\n\n```\ncom.casbytes.core\n├── CasbytesCoreServiceApplication\n├── audit                 # @Auditable + aspect-driven audit logs\n├── configuration         # cross-cutting Spring configuration\n├── infrastructure        # redis, kafka, casbin adapters\n├── modules               # package-by-feature ERP modules\n│   └── reference         # sample vertical slice (template)\n├── observability         # correlation id filter\n├── platform              # health aggregation\n├── security              # SecurityFilterChain + JWT extension point\n└── shared                # api envelope, exceptions, utilities\n```\n\nFull file listing is generated in CI or locally via:\n\n```bash\nfind . -type f \\( -path './target/*' -o -path './.git/*' \\) -prune -o -type f -print | sed 's|^\\./||' | sort\n```\n\n## Production \u0026 Kubernetes readiness (summary)\n\n1. **Ports:** expose `8080` (traffic) and `8081` (management) separately in the Service mesh / ingress policy.\n2. **Probes:** Liveness `GET http://127.0.0.1:8081/actuator/health/liveness` (when enabled) or `/actuator/health`; Readiness should include downstream checks as appropriate.\n3. **Secrets:** mount as env vars or files from a secret manager (Vault, AWS Secrets Manager, GSM).\n4. **Config:** use `SPRING_PROFILES_ACTIVE=prod` and externalize overrides via environment variables matching the `CASBYTES_*` and `SPRING_*` placeholders in `application.yml`.\n5. **Observability:** scrape Prometheus from `:8081/actuator/prometheus` via network policy–limited monitoring namespaces.\n6. **HPA:** CPU + memory + custom metrics (Kafka lag, HTTP latency) once baselines exist.\n\n## Major commands (quick reference)\n\nRun all commands from the **repository root** (`casbytes-core/`). On Windows, use `mvnw.cmd` instead of `./mvnw` where applicable.\n\n### Build \u0026 package\n\n```bash\n./mvnw clean compile              # compile only\n./mvnw clean package              # JAR in target/ (runs tests unless -DskipTests)\n./mvnw clean package -DskipTests    # package without tests\n./mvnw clean verify               # lifecycle through verify (tests + JaCoCo report)\n```\n\n### Run the application (Flyway runs on startup)\n\nMigrations apply automatically when Spring Boot starts against the configured datasource.\n\n```bash\n# Recommended local profile (YAML aligns with docker-compose host ports: Postgres 5433, Redis 6380, …)\n./mvnw spring-boot:run -Dspring-boot.run.profiles=dev\n\n# No explicit profile (uses application.yml + application-default.yml when implicit default profile is active)\n./mvnw spring-boot:run\n\n# After ./mvnw package\njava -jar target/casbytes-core-service-0.1.0-SNAPSHOT.jar --spring.profiles.active=dev\n```\n\n### Local infrastructure (Docker Compose)\n\n```bash\n# Core data stores only (typical for API dev)\ndocker compose up -d postgres redis\n\n# Full stack (see docker-compose.yml comments for ports)\ndocker compose up -d\n\n# Flyway only: applies SQL under src/main/resources/db/migration (uses compose env for DB)\ndocker compose run --rm flyway\n```\n\nExport `CASBYTES_DATASOURCE_PASSWORD` if your compose file expects it (see `docker-compose.yml`).\n\n### Tests\n\n```bash\n./mvnw test                       # unit tests (JUnit tag \"integration\" excluded by default)\n./mvnw -Pintegration test         # includes Testcontainers ITs (Docker required)\n./mvnw test -Dtest=SomeTest       # single test class (optional)\n```\n\nIntegration ITs: `com.casbytes.core.integration.security.CasbytesContainersIT` — skipped when Docker is unavailable (`@Testcontainers(disabledWithoutDocker = true)`).\n\n### Code quality \u0026 formatting\n\n```bash\n./mvnw spotless:check             # fail if Java formatting / imports drift\n./mvnw spotless:apply             # auto-fix formatting\n./mvnw -Pquality verify           # Checkstyle + PMD on verify (see pom); still run spotless:check in CI\n```\n\nWith **`-Pquality`**, `verify` runs **Checkstyle** and **PMD**. Run **Spotless** in addition (`spotless:check`) in CI or pre-commit.\n\n**JaCoCo** (coverage): runs on every `./mvnw verify` — reports under `target/site/jacoco/` (`jacoco.xml` for Sonar).\n\n**SonarQube / SonarCloud** (server UI; requires host + token):\n\n```bash\n./mvnw verify sonar:sonar \\\n  -Dsonar.host.url=https://your-sonar.example \\\n  -Dsonar.login=\"$SONAR_TOKEN\"\n```\n\nProject defaults live in `sonar-project.properties` (adjust `sonar.projectKey` for your org).\n\nMore detail: `config/build/README`.\n\n### Git hooks (pre-commit: tests + Spotless)\n\nHooks live in `scripts/git-hooks/`. Git does **not** use them until configured **once per clone**:\n\n```bash\ngit config core.hooksPath scripts/git-hooks\n```\n\nThen `git commit` runs `./mvnw test` and `./mvnw spotless:check`. Emergency bypass: `SKIP_PRE_COMMIT=1 git commit ...`  \nIntelliJ: enable **Run Git hooks** in commit settings. See `scripts/git-hooks/README`.\n\n### Docs (security \u0026 Casbin)\n\nSee `docs/OAUTH2_AND_CASBIN.md` for OAuth2 issuer/JWKS, Casbin JDBC/reload, and CI notes.\n\n## License\n\nProprietary — CasBytes. All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimajkumar%2Fcasbytes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimajkumar%2Fcasbytes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimajkumar%2Fcasbytes/lists"}