chore: Refactor codebase and add developer documentation

[SizzleUnrlsd]

Context

The current codebase is functional but hard to navigate and maintain due to inconsistent module boundaries, mixed responsibilities, and missing/partial documentation. This issue tracks a structured refactor and the creation of clear developer docs so contributors can understand architecture, workflows, and extension points quickly.

Goals

• Improve maintainability and readability (cleaner structure, clearer responsibilities).
• Reduce coupling and remove duplication.
• Add/refresh documentation to make onboarding and contributions easier.
• Keep behavior identical (no feature changes unless explicitly stated).

Scope

Refactor

• Identify and document current architecture pain points (modules, ownership, flows).
• Restructure folders/modules to reflect responsibilities (e.g., core/, cli/, analysis/, runtime/, utils/).
• Enforce consistent naming conventions and public/private APIs per module.
• Extract shared logic into common utilities (avoid copy-pasted helpers).
• Improve error handling consistency (error types/messages, exit codes).
• Add/adjust unit tests around refactored hotspots to ensure no regressions.

Documentation

Create or update:

• README.md (what it is, quick start, minimal examples)
• docs/ARCHITECTURE.md (high-level design, core flows, key abstractions)
• docs/DEVELOPMENT.md (build/test/lint/format, local dev workflow)
• docs/CONFIGURATION.md (config files, env vars, CLI flags)
• docs/CONTRIBUTING.md (coding style, PR process, commit conventions)

Non-goals

• No new features.
• No breaking CLI changes (unless explicitly approved).
• No broad stylistic rewrites without justification (prefer mechanical refactors + clear improvements).

Proposed plan

1. Audit: map current modules, responsibilities, and dependencies.
2. Design: propose target structure (short RFC in a comment or docs/REFRACTOR_PLAN.md).
3. Mechanical refactor: move/rename modules, adjust imports/includes, update build scripts.
4. Stabilize: tests + CI green, ensure behavior parity.
5. Docs: write/update docs aligned with the new structure.
6. Polish: final pass for naming consistency + dead code removal.

Acceptance criteria

• New module/folder structure merged and documented.
• No functional regressions: existing tests pass; CI green.
• Clear entry points documented (main CLI entry, core pipeline, key APIs).
• Added/updated docs listed in “Documentation” section exist and are accurate.
• Public interfaces are explicit (what’s intended for reuse vs internal).
• Changelog/release notes updated if the refactor impacts users (even if no breaking change).

Checklist (implementation)

• Create docs/ARCHITECTURE.md
• Create docs/DEVELOPMENT.md
• Create docs/CONFIGURATION.md
• Create/update docs/CONTRIBUTING.md
• Update README.md
• Add/refine tests for refactored modules
• Remove dead code and unused dependencies
• Ensure consistent logging/error style

Notes

• Keep commits small and reviewable (move/rename-only commits first, then logic cleanups).
• Prefer automated tooling for formatting/linting to avoid noisy diffs.