How yawnbear/imaginehack2026 works
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: page.tsx Dashboards · routes.py HTTP routes · rules_service.py Rules service · store.py Store layer
Components 24
Frontend
Next.js operator console and shared UI
- App shell · Global layout and dashboard chrome
app/layout.tsx - Dashboard layout · App Router dashboard scaffold
app/(dashboard)/layout.tsx - Shell UI · Navigation, profile, theme, and page framing
app/components/AppShell.tsx - Dashboards · Overview and capability pages for agents, rules, workflows, threats, audit, energy, and search
app/(dashboard)/page.tsx - Agents UI · Agent manager and builder surfaces
app/(dashboard)/agents/AgentsManager.tsx - Rules UI · Rule authoring and management surface
app/(dashboard)/rules/RulesManager.tsx - Workflows UI · Workflow manager and graph views
app/(dashboard)/workflows/WorkflowsManager.tsx - Support tools · Search, findings, exports, modals, charts, and assistant guidance
app/components/GlobalSearch.tsx - API client · Client-side API access and shared types/session/toast helpers
app/lib/api.ts
Backend
FastAPI policy and intelligence engine
- Backend app · Backend entrypoint and application startup
backend/main.py - HTTP routes · Thin route handlers for agents, rules, threats, workflows, and assets
backend/app/api/routes.py - Rules service · Rule evaluation, clashes, templates, and persistence orchestration
backend/app/services/rules_service.py - Agents service · Agent orchestration, recommendations, and summaries
backend/app/services/agents_service.py - Workflows service · Workflow orchestration and summaries
backend/app/services/workflows_service.py - Threats service · Criticality scoring and report generation
backend/app/services/threats_service.py - Agent runtime · Low-level agent I/O execution contracts
backend/app/agent/runtime.py - Rules engine · Operators, clash handling, and evaluation logic
backend/app/rules/engine.py - Agent router · Routes work across agent capabilities and AI calls
backend/app/agents/router.py - Threat engine · Criticality and report logic for findings
backend/app/threats/criticality.py - Store layer · Store interfaces and concrete PG/assets storage
backend/app/services/store.py
Data & Infra
Persistence and external integrations
- Cloud inputs · Cloud event and scan source ingestion
backend/app/services/cloud_event_sources.py - Postgres/Supabase · Persistent storage for findings, rules, workflows, energy, and audit records
- Gemini AI · Model provider used by agent and recommendation workflows
- Audit & exports · Approval, audit trail, and exportable reporting
app/components/AuditExport.tsx
Connections 30
- 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