# yawnbear/imaginehack2026 architecture

> Architecture diagram of the GitHub repository yawnbear/imaginehack2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yawnbear/imaginehack2026
- Repository: https://github.com/yawnbear/imaginehack2026

## Overview

1. **Repository shape**
   - SafeCloud is a two-tier monorepo: a **Next.js/React frontend** in `app/` and a **FastAPI Python backend** in `backend/`.
   - The product centers on cloud governance workflows: scanning, rule evaluation, AI analysis, recommendations, approval, audit, and reporting.

2. **Frontend shell and routing**
   - The frontend uses the Next.js App Router with a dashboard layout under `app/(dashboard)/`.
   - `app/layout.tsx`, `app/(dashboard)/layout.tsx`, and `app/components/AppShell.tsx` define the global shell, navigation, and shared UI chrome.
   - Pages are grouped by capability: **agents, rules, workflows, threats, audit, energy, search, dashboard**.

3. **Frontend feature surfaces**
   - Each major domain has a page and one or more manager components, for example:
     - `AgentsManager` / `AgentAIBuilder`
     - `RulesManager`
     - `WorkflowsManager` / `WorkflowGraph`
   - Supporting components provide reusable UX for search, charts, modals, exports, theme/profile controls, and assistant-style guidance.

4. **Frontend data access boundary**
   - `app/lib/api.ts` is the main client-side API boundary to the backend.
   - `app/lib/types.ts`, `format.ts`, `session.tsx`, `toast.tsx`, and `mockData.ts` hold shared client concerns such as typing, formatting, session state, notifications, and fallback/demo data.
   - The frontend is presentation-heavy; domain logic is mostly delegated to the backend.

5. **Backend service boundary**
   - The backend is organized as a layered FastAPI app:
     - `app/main.py` / `backend/main.py` for startup
     - `app/api/` for HTTP routing
     - `app/services/` for business logic and persistence
     - `app/schemas/` for request/response contracts
     - `app/rules/`, `app/threats/`, `app/agents/`, `app/agent/` for domain behavior
   - This separation is important for the architecture diagram: API routes are thin, while services and domain modules contain the core logic.

6. **Core domain subsystems**
   - **Rules**: rule definitions, operators, clash handling, templates, and an evaluation engine live under `app/rules/`.
   - **Threats**: criticality scoring and report generation are under `app/threats/`.
   - **Agents**: agent routing, AI client integration, summaries, and recommendations live under `app/agents/`.
   - **Workflows**: workflow orchestration and summaries are handled through `app/services/workflows_service.py` and related API/routes.
   - These domains map directly to the frontend sections and should be drawn as first-class bounded contexts.

7. **AI agent runtime path**
   - There is a dedicated agent execution layer in `app/agent/runtime.py`, separate from higher-level agent orchestration in `app/agents/`.
   - The runtime likely handles execution of agent I/O contracts, while `ai_client.py`, `router.py`, and `recommendations.py` handle model calls and decision routing.
   - The README’s “multi-agent” model is reflected in the codebase as a specialized subsystem rather than a generic chat layer.

8. **Persistence and infrastructure**
   - Persistence is abstracted through `app/services/store.py`, `pg_store.py`, `assets_store.py`, and seeded data modules.
   - The repo references **PostgreSQL/Supabase** in the README, so the backend likely stores findings, rules, workflows, energy metrics, and audit-related records there.
   - `backend/alembic/` indicates database migrations are part of the architecture.
   - The architecture should show the backend as reading/writing a database, with a store abstraction between services and storage.

9. **Data ingestion and cloud-event inputs**
   - `cloud_event_sources.py` and `scan_sources.py` suggest the system ingests cloud/resource signals from external sources before analysis.
   - This input path feeds the rules engine and downstream AI agents, producing findings and recommendations.
   - The data flow is: external cloud/resource events → scan/ingest services → rule evaluation and classification → threats/energy/agent workflows.

10. **Governance, approvals, and auditability**
   - The README’s human-in-the-loop requirement is reflected in audit-related pages and backend schemas/services.
   - `app/components/AuditExport.tsx`, `ESGReportExport.tsx`, and audit-facing backend schemas indicate exportable records and traceability.
   - The architecture should show approval/audit as a cross-cutting control plane over recommendations and actions, not just another UI page.

11. **Operational support, testing, and documentation**
   - `backend/tests/` is extensive and covers APIs, schemas, engine logic, workflow routing, threat reports, ingestion, and database behavior; this suggests the backend is the primary source of correctness.
   - `docs/superpowers/` and `plan.md` capture the design evolution of rules, agents, threats, and workflows.
   - `watch/` and `safecloud-agent.py` look like supporting tooling/simulation assets rather than core product surfaces.
   - For deployment, the README points to **Vercel** for the frontend and **Render** for the backend, which is relevant if your diagram includes runtime placement.

12. **High-level end-to-end flow**
   - The canonical flow is: cloud signals enter the backend, are normalized and evaluated by rules/services, then enriched by AI agent logic, surfaced in the dashboard, reviewed by humans, and finally exported or audited.
   - The frontend is the operator console; the backend is the policy and intelligence engine; PostgreSQL/Supabase is the persistence layer; Gemini is the external AI dependency.

Main entry points: [`app/(dashboard)/page.tsx`](https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/page.tsx) (Dashboards), [`backend/app/api/routes.py`](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/api/routes.py) (HTTP routes), [`backend/app/services/rules_service.py`](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/rules_service.py) (Rules service), [`backend/app/services/store.py`](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/store.py) (Store layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_layout["App shell<br/>next shell<br/>[layout.tsx]"]
  node_dashboard_layout["Dashboard layout<br/>route shell<br/>[layout.tsx]"]
  node_app_shell["Shell UI<br/>ui chrome<br/>[AppShell.tsx]"]
  node_dashboard_pages["Dashboards<br/>operator pages<br/>[page.tsx]"]
  node_agents_ui["Agents UI<br/>feature surface<br/>[AgentsManager.tsx]"]
  node_rules_ui["Rules UI<br/>feature surface<br/>[RulesManager.tsx]"]
  node_workflows_ui["Workflows UI<br/>feature surface"]
  node_support_ui["Support tools<br/>shared UI<br/>[GlobalSearch.tsx]"]
  node_api_client["API client<br/>frontend boundary<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["Backend app<br/>fastapi startup<br/>[main.py]"]
  node_api_routes["HTTP routes<br/>api layer<br/>[routes.py]"]
  node_rules_service["Rules service<br/>domain service<br/>[rules_service.py]"]
  node_agents_service["Agents service<br/>domain service<br/>[agents_service.py]"]
  node_workflows_service["Workflows service<br/>domain service"]
  node_threats_service["Threats service<br/>domain service<br/>[threats_service.py]"]
  node_agent_runtime["Agent runtime<br/>execution layer<br/>[runtime.py]"]
  node_rules_engine["Rules engine<br/>policy engine<br/>[engine.py]"]
  node_agent_router["Agent router<br/>decision routing<br/>[router.py]"]
  node_threats_engine["Threat engine<br/>risk analysis<br/>[criticality.py]"]
  node_store["Store layer<br/>persistence abstraction<br/>[store.py]"]
end

subgraph group_infra["Data & Infra"]
  node_cloud_inputs[("Cloud inputs<br/>ingestion sources")]
  node_database[("Postgres/Supabase<br/>database")]
  node_gemini(("Gemini AI<br/>external model"))
  node_exports_audit["Audit & exports<br/>governance plane<br/>[AuditExport.tsx]"]
end

node_app_layout -->|"wraps"| node_dashboard_layout
node_dashboard_layout -->|"renders"| node_app_shell
node_app_shell -->|"hosts"| node_dashboard_pages
node_dashboard_pages -->|"routes to"| node_agents_ui
node_dashboard_pages -->|"routes to"| node_rules_ui
node_dashboard_pages -->|"routes to"| node_workflows_ui
node_dashboard_pages -->|"uses"| node_support_ui
node_agents_ui -->|"fetches"| node_api_client
node_rules_ui -->|"fetches"| node_api_client
node_workflows_ui -->|"fetches"| node_api_client
node_api_client -->|"calls"| node_api_routes
node_backend_main -->|"mounts"| node_api_routes
node_api_routes -->|"delegates"| node_rules_service
node_api_routes -->|"delegates"| node_agents_service
node_api_routes -->|"delegates"| node_workflows_service
node_api_routes -->|"delegates"| node_threats_service
node_rules_service -->|"evaluates"| node_rules_engine
node_agents_service -->|"orchestrates"| node_agent_router
node_agent_router -->|"executes"| node_agent_runtime
node_agent_router -->|"calls"| node_gemini
node_cloud_inputs -->|"feeds"| node_rules_service
node_rules_service -->|"emits"| node_threats_service
node_threats_service -->|"prioritizes"| node_workflows_service
node_rules_service -->|"reads/writes"| node_store
node_agents_service -->|"reads/writes"| node_store
node_workflows_service -->|"reads/writes"| node_store
node_threats_service -->|"reads/writes"| node_store
node_store -->|"persists"| node_database
node_exports_audit -->|"records"| node_database
node_exports_audit -->|"surfaces"| node_dashboard_pages

click node_app_layout "https://github.com/yawnbear/imaginehack2026/blob/main/app/layout.tsx"
click node_dashboard_layout "https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/layout.tsx"
click node_app_shell "https://github.com/yawnbear/imaginehack2026/blob/main/app/components/AppShell.tsx"
click node_dashboard_pages "https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/page.tsx"
click node_agents_ui "https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/agents/AgentsManager.tsx"
click node_rules_ui "https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/rules/RulesManager.tsx"
click node_workflows_ui "https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/workflows/WorkflowsManager.tsx"
click node_support_ui "https://github.com/yawnbear/imaginehack2026/blob/main/app/components/GlobalSearch.tsx"
click node_api_client "https://github.com/yawnbear/imaginehack2026/blob/main/app/lib/api.ts"
click node_backend_main "https://github.com/yawnbear/imaginehack2026/blob/main/backend/main.py"
click node_api_routes "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/api/routes.py"
click node_rules_service "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/rules_service.py"
click node_agents_service "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/agents_service.py"
click node_workflows_service "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/workflows_service.py"
click node_threats_service "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/threats_service.py"
click node_agent_runtime "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/agent/runtime.py"
click node_rules_engine "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/rules/engine.py"
click node_agent_router "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/agents/router.py"
click node_threats_engine "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/threats/criticality.py"
click node_store "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/store.py"
click node_cloud_inputs "https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/cloud_event_sources.py"
click node_exports_audit "https://github.com/yawnbear/imaginehack2026/blob/main/app/components/AuditExport.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_dashboard_layout,node_app_shell,node_dashboard_pages,node_agents_ui,node_rules_ui,node_workflows_ui,node_support_ui,node_api_client toneBlue
class node_backend_main,node_api_routes,node_rules_service,node_agents_service,node_workflows_service,node_threats_service,node_agent_runtime,node_rules_engine,node_agent_router,node_threats_engine,node_store toneAmber
class node_cloud_inputs,node_database,node_gemini,node_exports_audit toneMint
```

## Components

### Frontend

Next.js operator console and shared UI

- [App shell](https://github.com/yawnbear/imaginehack2026/blob/main/app/layout.tsx): next shell · Global layout and dashboard chrome · `app/layout.tsx`
- [Dashboard layout](https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/layout.tsx): route shell · App Router dashboard scaffold · `app/(dashboard)/layout.tsx`
- [Shell UI](https://github.com/yawnbear/imaginehack2026/blob/main/app/components/AppShell.tsx): ui chrome · Navigation, profile, theme, and page framing · `app/components/AppShell.tsx`
- [Dashboards](https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/page.tsx): operator pages · Overview and capability pages for agents, rules, workflows, threats, audit, energy, and search · `app/(dashboard)/page.tsx`
- [Agents UI](https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/agents/AgentsManager.tsx): feature surface · Agent manager and builder surfaces · `app/(dashboard)/agents/AgentsManager.tsx`
- [Rules UI](https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/rules/RulesManager.tsx): feature surface · Rule authoring and management surface · `app/(dashboard)/rules/RulesManager.tsx`
- [Workflows UI](https://github.com/yawnbear/imaginehack2026/blob/main/app/(dashboard)/workflows/WorkflowsManager.tsx): feature surface · Workflow manager and graph views · `app/(dashboard)/workflows/WorkflowsManager.tsx`
- [Support tools](https://github.com/yawnbear/imaginehack2026/blob/main/app/components/GlobalSearch.tsx): shared UI · Search, findings, exports, modals, charts, and assistant guidance · `app/components/GlobalSearch.tsx`
- [API client](https://github.com/yawnbear/imaginehack2026/blob/main/app/lib/api.ts): frontend boundary · Client-side API access and shared types/session/toast helpers · `app/lib/api.ts`

### Backend

FastAPI policy and intelligence engine

- [Backend app](https://github.com/yawnbear/imaginehack2026/blob/main/backend/main.py): fastapi startup · Backend entrypoint and application startup · `backend/main.py`
- [HTTP routes](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/api/routes.py): api layer · Thin route handlers for agents, rules, threats, workflows, and assets · `backend/app/api/routes.py`
- [Rules service](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/rules_service.py): domain service · Rule evaluation, clashes, templates, and persistence orchestration · `backend/app/services/rules_service.py`
- [Agents service](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/agents_service.py): domain service · Agent orchestration, recommendations, and summaries · `backend/app/services/agents_service.py`
- [Workflows service](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/workflows_service.py): domain service · Workflow orchestration and summaries · `backend/app/services/workflows_service.py`
- [Threats service](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/threats_service.py): domain service · Criticality scoring and report generation · `backend/app/services/threats_service.py`
- [Agent runtime](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/agent/runtime.py): execution layer · Low-level agent I/O execution contracts · `backend/app/agent/runtime.py`
- [Rules engine](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/rules/engine.py): policy engine · Operators, clash handling, and evaluation logic · `backend/app/rules/engine.py`
- [Agent router](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/agents/router.py): decision routing · Routes work across agent capabilities and AI calls · `backend/app/agents/router.py`
- [Threat engine](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/threats/criticality.py): risk analysis · Criticality and report logic for findings · `backend/app/threats/criticality.py`
- [Store layer](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/store.py): persistence abstraction · Store interfaces and concrete PG/assets storage · `backend/app/services/store.py`

### Data & Infra

Persistence and external integrations

- [Cloud inputs](https://github.com/yawnbear/imaginehack2026/blob/main/backend/app/services/cloud_event_sources.py): ingestion sources · Cloud event and scan source ingestion · `backend/app/services/cloud_event_sources.py`
- **Postgres/Supabase**: database · Persistent storage for findings, rules, workflows, energy, and audit records
- **Gemini AI**: external model · Model provider used by agent and recommendation workflows
- [Audit & exports](https://github.com/yawnbear/imaginehack2026/blob/main/app/components/AuditExport.tsx): governance plane · Approval, audit trail, and exportable reporting · `app/components/AuditExport.tsx`

## Connections

- App shell → Dashboard layout: wraps · Root layout hands off to dashboard shell
- Dashboard layout → Shell UI: renders · Dashboard route uses shared shell chrome
- Shell UI → Dashboards: hosts · Shell frames the operator pages
- Dashboards → Agents UI: routes to · Agent capability surface
- Dashboards → Rules UI: routes to · Rules capability surface
- Dashboards → Workflows UI: routes to · Workflow capability surface
- Dashboards → Support tools: uses · Shared search, charts, and assistant helpers
- Agents UI → API client: fetches · Frontend state is backed by backend APIs
- Rules UI → API client: fetches · Rules management reads and updates via API
- Workflows UI → API client: fetches · Workflow UI synchronizes with backend APIs
- API client → HTTP routes: calls · Client boundary to HTTP API
- Backend app → HTTP routes: mounts · Application startup wires route modules
- HTTP routes → Rules service: delegates · Rules endpoints stay thin
- HTTP routes → Agents service: delegates · Agents endpoints stay thin
- HTTP routes → Workflows service: delegates · Workflow endpoints stay thin
- HTTP routes → Threats service: delegates · Threat endpoints stay thin
- Rules service → Rules engine: evaluates · Service relies on policy engine for rule logic
- Agents service → Agent router: orchestrates · Higher-level agent coordination and recommendations
- Agent router → Agent runtime: executes · Decision routing invokes runtime I/O contracts
- Agent router → Gemini AI: calls · Model-backed analysis and recommendation generation
- Cloud inputs → Rules service: feeds · Incoming cloud signals enter policy evaluation
- Rules service → Threats service: emits · Evaluated findings flow into threat scoring
- Threats service → Workflows service: prioritizes · Threat outputs inform workflow summaries and actions
- Rules service → Store layer: reads/writes · Rule definitions and evaluations persist through store abstraction
- Agents service → Store layer: reads/writes · Agent state and outputs persist through store abstraction
- Workflows service → Store layer: reads/writes · Workflow entities and summaries persist through store abstraction
- Threats service → Store layer: reads/writes · Threat reports and findings persist through store abstraction
- Store layer → Postgres/Supabase: persists · Concrete storage is PostgreSQL/Supabase
- Audit & exports → Postgres/Supabase: records · Governance artifacts and exports are audit-backed
- Audit & exports → Dashboards: surfaces · Audit and export controls appear in the operator console
