Skip to content

docs: add ARCHITECTURE.md + security ADRs (rounds 1-9) - #123

Merged
Akash29g merged 2 commits into
mainfrom
docs/architecture-and-adrs
Jul 22, 2026
Merged

docs: add ARCHITECTURE.md + security ADRs (rounds 1-9)#123
Akash29g merged 2 commits into
mainfrom
docs/architecture-and-adrs

Conversation

@Akash29g

Copy link
Copy Markdown
Owner

What

Adds project documentation:

  • ARCHITECTURE.md (repo root) — a living architecture overview: product/business
    context, requirements traceability (FR/NFR), tech stack, layered solution architecture,
    the 12-table data model, API conventions, frontend architecture, multi-tenancy, auth,
    SignalR, the invoice extraction pipeline (S3 → GuardDuty → Bedrock Nova), AWS
    infrastructure, CI/CD, the security-hardening summary, local dev, conventions, a
    round-by-round hardening timeline, and a glossary.
  • docs/adr/0001-0005 — Architecture Decision Records for the security & CI/CD
    decisions made across the hardening rounds:
    • 0001 Transport hardening (HSTS, security headers, CORS lock-down)
    • 0002 Content Security Policy (API + SPA)
    • 0003 Tenant isolation via EF Core global query filters
    • 0004 JWT auth + DB-backed rotating refresh tokens
    • 0005 Per-layer code coverage gates in CI

Each ADR follows the standard format: Context → Alternatives Considered → Decision →
Implementation → Consequences → Testing & Verification → Related PRs → Follow-ups.

Why

We had substantial security/architecture work spread across rounds 0–9 and the
harden/prod-security pass, but the reasoning behind those decisions lived only in
PRs and chat history. This captures the "why" as durable, reviewable docs — useful for
onboarding, future maintenance, and the project's Documentation evaluation criterion.

Scope / safety

  • Docs-only. No application code, config, schema, or CI behaviour changes.
  • Build / tests / coverage gate are unaffected.

Notes for reviewer

  • These docs describe existing behaviour; a couple of points to sanity-check against the
    current code: 404-vs-403 on cross-tenant reads (ADR-0003), access-token TTL = 20 min
    (ADR-0004), and the RDS/super-admin infra follow-ups noted as planned.
  • The ADR index lives at the bottom of ARCHITECTURE.md; links point to docs/adr/.

Checklist

  • Docs only — no code/behaviour change
  • Links between ARCHITECTURE.md and ADRs resolve
  • Cross-review (CODEOWNERS)

@Akash29g
Akash29g requested a review from sumitgupta-cse July 22, 2026 15:25
@Akash29g
Akash29g requested a review from g9shubh as a code owner July 22, 2026 15:25
@Akash29g
Akash29g merged commit 420a516 into main Jul 22, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant