OH-2930: docs: architecture documentation and developer guides

[RishabhOrange]

User description

Summary

• Adds comprehensive architecture documentation under docs/architecture/ covering system overview, service layer, integrations, configuration, observability, and branching strategy
• Adds CLAUDE.md with directory map, layering rules, coding conventions, and feature-addition guide for AI and human developers
• Adds AGENTS.md with agent-specific boundaries, module responsibilities, PR checklist, and documentation update triggers

Test plan

• Review documentation accuracy against source code
• Verify all Mermaid diagrams render correctly on GitHub
• Confirm branching strategy matches current team workflow

Made with Cursor

---

CodeAnt-AI Description

Allow AWS access without hardcoded credentials for IRSA deployments

What Changed

• The library can now start AWS connections without access keys, so Kubernetes workloads using IAM Roles for Service Accounts can use the default AWS credential chain.
• The README and architecture docs now explain how to configure IRSA, required AWS region settings, and related library behavior.
• Version and release notes were updated to include the new support.

Impact

✅ Fewer deployment failures in Kubernetes
✅ Shorter setup for IRSA-based services
✅ Clearer configuration guidance for AWS access

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[codeant-ai]

CodeAnt AI is reviewing your PR.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

Suggestion: Add explicit log-size guidance so large values are truncated and full payloads are not logged. [custom_rule]

Severity Level: Minor ⚠️

Suggested change

	For production deployments, configure `python-json-logger` or equivalent so that codec log lines (which include byte counts) and exception stack traces are emitted as structured JSON fields rather than raw strings:
	For production deployments, configure `python-json-logger` or equivalent so that codec log lines (which include byte counts) and exception stack traces are emitted as structured JSON fields rather than raw strings, and enforce log-size limits by truncating long values and avoiding full message payload logging.

Why it matters? ⭐

This suggestion is directly aligned with the custom rule to check log size. The repo already uses structured INFO logging for codec operations and exception logging in src/pubsublib/common/codec.py, but the docs currently lack any guidance about truncating or limiting oversized values. Adding log-size guidance meaningfully addresses that observability concern.

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** docs/architecture/observability.md
**Line:** 134:134
**Comment:**
	*Custom Rule: Add explicit log-size guidance so large values are truncated and full payloads are not logged.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.

👍 | 👎

[codeant-ai]

Suggestion: In the fallback branch, the session is created without region_name, so callers that rely on IAM/instance-role credentials but pass aws_region will still lose region configuration and sns/sqs client creation can fail with NoRegionError. Keep using the provided region even when explicit credentials are not passed. [logic error]

Severity Level: Critical 🚨

- ❌ AWSPubSubAdapter initialization fails for IAM-role, no global region.
- ❌ SNS client creation fails, blocking publish and topic management.
- ❌ SQS client creation fails, blocking queue operations and polling.

Suggested change

	self.my_session = boto3.session.Session()
	self.my_session = boto3.session.Session(region_name=aws_region)

Steps of Reproduction ✅

1. Verify that `AWSPubSubAdapter` is defined in `src/pubsublib/aws/main.py:16` and that
there are no in-repo call sites (`Grep` for `AWSPubSubAdapter(` under `/workspace` only
returns the class definition), meaning this is a library entry point intended for external
callers.

2. In an external consumer (e.g., a Python REPL or service), import the adapter: `from
pubsublib.aws.main import AWSPubSubAdapter` (class at `src/pubsublib/aws/main.py:16`).

3. Run in an environment where IAM/instance-role or other default AWS credentials are
available but **no default region is configured** (no `AWS_REGION` / `AWS_DEFAULT_REGION`
environment variables and no region in `~/.aws/config`), then construct the adapter so
that credentials are omitted or falsy, for example:

   `AWSPubSubAdapter(aws_region="us-east-1", aws_access_key_id=None,
   aws_secret_access_key=None, redis_location="redis://localhost:6379")`.

   This call reaches `__init__` at lines `17–27` and, because the keys are falsy, executes
   the `else` branch at lines `28–35`, creating `boto3.session.Session()` **without**
   `region_name`.

4. During the same `__init__` call, observe that `self.my_session.client("sns")` at
`src/pubsublib/aws/main.py:36–40` (and `self.my_session.client("sqs")` at `41–45`)
attempts to create clients from a session with no region; in an environment with no global
region configured, boto3/botocore raises `botocore.exceptions.NoRegionError: You must
specify a region`, causing adapter initialization to fail and preventing later calls such
as `create_topic` (line `56`) and `create_queue` (line `155`) from ever being usable.

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** src/pubsublib/aws/main.py
**Line:** 35:35
**Comment:**
	*Logic Error: In the fallback branch, the session is created without `region_name`, so callers that rely on IAM/instance-role credentials but pass `aws_region` will still lose region configuration and `sns`/`sqs` client creation can fail with `NoRegionError`. Keep using the provided region even when explicit credentials are not passed.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.

👍 | 👎

[codeant-ai]

CodeAnt AI finished reviewing your PR.