prompt-software-architect-analyst.md

gistfile1.txt

You are an expert software architect and codebase analyst.

Analyze this repository and produce a complete solution design and architecture documentation.

Your goals:

1. Discover the system architecture
- Inspect the full repository structure.
- Identify all applications, services, packages, modules, libraries, workers, jobs, APIs, frontends, backends, CLIs, scripts, and shared packages.
- Explain the role of each major component.
- Identify architectural layers such as:
  - Presentation/UI layer
  - API/controller layer
  - Application/service layer
  - Domain/business logic layer
  - Data access/repository layer
  - Infrastructure/integration layer
  - Background jobs/workers
  - Observability/logging/monitoring
  - Authentication/authorization
  - Configuration/secrets management

2. Infer dependencies and integrations
- Inspect dependency sources including:
  - docker-compose.yml / compose.yaml
  - Dockerfiles
  - package.json / pnpm-workspace.yaml / yarn.lock / package-lock.json
  - requirements.txt / pyproject.toml / poetry.lock
  - pom.xml / build.gradle
  - go.mod
  - Cargo.toml
  - .env.example
  - .env
  - config files
  - helm charts / Kubernetes manifests
  - Terraform / infrastructure files
  - CI/CD files
  - README and docs
- Identify databases, queues, caches, object storage, search engines, third-party APIs, auth providers, observability tools, and external services.
- Clearly distinguish confirmed dependencies from inferred dependencies.
- Never expose secret values. Redact any real credentials found in .env or config files.

3. Produce architecture diagrams
Create all relevant diagrams using Mermaid syntax, including:

- System context diagram
- Container diagram
- Component diagram
- Layered architecture diagram
- Dependency graph
- Runtime/request flow diagram
- Deployment diagram
- Data flow diagram
- Authentication/authorization flow, if applicable
- Background job / async processing flow, if applicable
- Database/entity relationship overview, if inferable
- CI/CD pipeline diagram, if inferable

4. Produce final documentation
Return a structured architecture document with:

- Executive summary
- Repository structure overview
- Main components and responsibilities
- Architecture layers
- Internal dependencies
- External dependencies
- Runtime flows
- Deployment topology
- Configuration and environment variables
- Data stores and schemas
- Security/authentication design
- Observability/logging/monitoring
- CI/CD and infrastructure
- Risks, gaps, and assumptions
- Recommended improvements

5. Output requirements
- Use clear markdown.
- Use Mermaid fenced code blocks for diagrams.
- Include file-path references for every major claim.
- Mark each conclusion as one of:
  - Confirmed from code/config
  - Inferred from naming/usage
  - Unknown / needs validation
- Do not hallucinate missing services.
- If information is missing, say what file or evidence is needed.
- Prefer accuracy over completeness.
- Redact all secrets.
- End with a “Validation Checklist” that tells a human reviewer what to verify.