# grim-sudo/busqueda architecture

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

- Interactive diagram: https://gitdiagram.com/grim-sudo/busqueda
- Repository: https://github.com/grim-sudo/busqueda

## Overview

1. **Top-level deployment**: this repo is built to run as a **single Docker container**. The runtime boundary is one Linux container with **Nginx on port 80**, a **Flask backend in Python 3**, and an **internal Gitea simulation on port 3000**. There is no separate database, message queue, or external SaaS dependency.

2. **Request ingress and routing**: all browser traffic enters through **Nginx**. Nginx serves the compiled frontend assets and forwards application requests to the Flask API. The frontend is built during image creation, so the final container does **not** need Node.js at runtime.

3. **Frontend subsystem**: the UI is a **Vite + React + TypeScript** app under `frontend/`. It is a small client-side dashboard with three visible pieces: `SearchPanel`, `ServiceTable`, and `StatusBar`. The UI is responsible for calling backend endpoints and rendering service registry/status data; it does not do server-side rendering.

4. **Backend API subsystem**: `backend/app.py` is the main Flask application. It exposes:
   - `GET /api/status` for basic application metadata,
   - `GET /api/health` for container health and internal IP visibility,
   - `GET /api/services` for the full registry dataset, protected by an `X-Api-Key`,
   - `POST /search` for service search.
   This backend is the central business-logic layer for the app.

5. **Data model / registry source**: the service inventory appears to come from backend-local code, primarily `fake_services.py` and configuration in `config.py`. The backend acts as the authoritative source for service registry content that the frontend displays.

6. **Static asset delivery**: the frontend bundle and public assets are served as static files, likely through the Flask/Nginx combination rather than a separate CDN or app server. That means the browser talks to one origin for both UI and API, simplifying the diagram to a single user-facing entry point.

7. **Internal simulation service**: `backend/gitea_sim.py` represents an internal **Gitea-like service** used for the lab theme. It is not a full external dependency; it exists inside the container boundary to simulate a developer repository exposure and to support the challenge narrative around leaked implementation details.

8. **Startup and orchestration**: `entrypoint.sh` is the container bootstrap layer. It coordinates startup of the web stack and any initialization needed for the runtime environment, while `backend/scripts/system_check.py` suggests an internal diagnostic or readiness-check path.

9. **Configuration boundaries**: `backend/config.py` and `backend/nginx.conf` are the main operational configuration points. They define runtime behavior such as service addresses, proxy behavior, and environment-sensitive values like the embedded container IP or flag defaults mentioned in the README.

10. **Security-relevant architecture**: the repo intentionally contains an **exposed `.git` directory** served as static content and a **vulnerable `/search` path** that uses templating on user input. Those are not separate subsystems, but they are important boundaries in the architecture because they bridge the public web tier to privileged backend behavior.

11. **Overall data flow**: browser → Nginx → Flask API → registry data / simulated internal services. The frontend consumes status and service data, while the search path accepts user-supplied formatting parameters that are processed server-side. The internal Gitea simulation and exposed repo metadata act as supporting sources for the lab’s intended workflow.

12. **Operational shape**: this is best diagrammed as a **monolith-in-a-container** with a proxy front end, a single Python application backend, and a compiled SPA frontend. The main architectural separation is between **public web ingress**, **application logic**, and **internal simulation/debug artifacts** rather than between multiple deployable services.

Main entry points: [`backend/app.py`](https://github.com/grim-sudo/busqueda/blob/main/backend/app.py) (Flask API), [`frontend/src/App.tsx`](https://github.com/grim-sudo/busqueda/blob/main/frontend/src/App.tsx) (Dashboard), [`backend/nginx.conf`](https://github.com/grim-sudo/busqueda/blob/main/backend/nginx.conf) (Nginx), [`entrypoint.sh`](https://github.com/grim-sudo/busqueda/blob/main/entrypoint.sh) (Entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Container runtime"]
  node_browser(("Browser<br/>client"))
  node_dockerfile["Dockerfile<br/>container build"]
  node_entrypoint["Entrypoint<br/>bootstrap<br/>[entrypoint.sh]"]
  node_nginx["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_index["Index page<br/>spa shell<br/>[index.html]"]
  node_frontend_main["App bootstrap<br/>react entry<br/>[main.tsx]"]
  node_frontend_app["Dashboard<br/>react app<br/>[App.tsx]"]
  node_search_panel["Search panel<br/>ui component<br/>[SearchPanel.tsx]"]
  node_service_table["Service table<br/>ui component<br/>[ServiceTable.tsx]"]
  node_status_bar["Status bar<br/>ui component<br/>[StatusBar.tsx]"]
  node_vite_config["Vite config<br/>build config<br/>[vite.config.ts]"]
end

subgraph group_backend["Backend"]
  node_flask_app["Flask API<br/>web api<br/>[app.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_fake_services[("Registry data<br/>data source<br/>[fake_services.py]")]
  node_gitea_sim["Gitea sim<br/>internal service<br/>[gitea_sim.py]"]
  node_system_check["System check<br/>diagnostic<br/>[system_check.py]"]
end

node_browser -->|"HTTP"| node_nginx
node_nginx -->|"serve"| node_frontend_index
node_nginx -->|"proxy /api"| node_flask_app
node_entrypoint -->|"start"| node_nginx
node_entrypoint -->|"start"| node_flask_app
node_dockerfile -->|"runtime image"| node_entrypoint
node_dockerfile -->|"build frontend"| node_vite_config
node_frontend_index -->|"load"| node_frontend_main
node_frontend_main -->|"mount"| node_frontend_app
node_frontend_app -->|"compose"| node_search_panel
node_frontend_app -->|"compose"| node_service_table
node_frontend_app -->|"compose"| node_status_bar
node_frontend_app -->|"fetch data"| node_flask_app
node_flask_app -->|"reads"| node_backend_config
node_flask_app -->|"serves registry"| node_fake_services
node_flask_app -->|"internal sim"| node_gitea_sim
node_flask_app -->|"diagnostics"| node_system_check

click node_dockerfile "https://github.com/grim-sudo/busqueda/tree/main/Dockerfile"
click node_entrypoint "https://github.com/grim-sudo/busqueda/blob/main/entrypoint.sh"
click node_nginx "https://github.com/grim-sudo/busqueda/blob/main/backend/nginx.conf"
click node_frontend_index "https://github.com/grim-sudo/busqueda/blob/main/frontend/index.html"
click node_frontend_main "https://github.com/grim-sudo/busqueda/blob/main/frontend/src/main.tsx"
click node_frontend_app "https://github.com/grim-sudo/busqueda/blob/main/frontend/src/App.tsx"
click node_search_panel "https://github.com/grim-sudo/busqueda/blob/main/frontend/src/components/SearchPanel.tsx"
click node_service_table "https://github.com/grim-sudo/busqueda/blob/main/frontend/src/components/ServiceTable.tsx"
click node_status_bar "https://github.com/grim-sudo/busqueda/blob/main/frontend/src/components/StatusBar.tsx"
click node_vite_config "https://github.com/grim-sudo/busqueda/blob/main/frontend/vite.config.ts"
click node_flask_app "https://github.com/grim-sudo/busqueda/blob/main/backend/app.py"
click node_backend_config "https://github.com/grim-sudo/busqueda/blob/main/backend/config.py"
click node_fake_services "https://github.com/grim-sudo/busqueda/blob/main/backend/fake_services.py"
click node_gitea_sim "https://github.com/grim-sudo/busqueda/blob/main/backend/gitea_sim.py"
click node_system_check "https://github.com/grim-sudo/busqueda/blob/main/backend/scripts/system_check.py"

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_browser,node_dockerfile,node_entrypoint,node_nginx toneBlue
class node_frontend_index,node_frontend_main,node_frontend_app,node_search_panel,node_service_table,node_status_bar,node_vite_config toneAmber
class node_flask_app,node_backend_config,node_fake_services,node_gitea_sim,node_system_check toneMint
```

## Components

### Container runtime

Single-container deployment, startup, and request ingress.

- **Browser**: client · User-facing entry point that reaches the app over one origin.
- [Dockerfile](https://github.com/grim-sudo/busqueda/tree/main/Dockerfile): container build · Builds the single runtime image and compiles the frontend during image creation. · `Dockerfile`
- [Entrypoint](https://github.com/grim-sudo/busqueda/blob/main/entrypoint.sh): bootstrap · Container startup script that launches the web stack. · `entrypoint.sh`
- [Nginx](https://github.com/grim-sudo/busqueda/blob/main/backend/nginx.conf): reverse proxy · Public ingress on port 80; serves static frontend assets and proxies API traffic. · `backend/nginx.conf`

### Frontend

Vite + React client-side dashboard.

- [Index page](https://github.com/grim-sudo/busqueda/blob/main/frontend/index.html): spa shell · HTML entry for the client-side app. · `frontend/index.html`
- [App bootstrap](https://github.com/grim-sudo/busqueda/blob/main/frontend/src/main.tsx): react entry · Bootstraps the React/TypeScript application. · `frontend/src/main.tsx`
- [Dashboard](https://github.com/grim-sudo/busqueda/blob/main/frontend/src/App.tsx): react app · Top-level client dashboard composition and API interaction. · `frontend/src/App.tsx`
- [Search panel](https://github.com/grim-sudo/busqueda/blob/main/frontend/src/components/SearchPanel.tsx): ui component · Search input and request controls for backend search. · `frontend/src/components/SearchPanel.tsx`
- [Service table](https://github.com/grim-sudo/busqueda/blob/main/frontend/src/components/ServiceTable.tsx): ui component · Renders the service registry and status rows. · `frontend/src/components/ServiceTable.tsx`
- [Status bar](https://github.com/grim-sudo/busqueda/blob/main/frontend/src/components/StatusBar.tsx): ui component · Shows application and runtime status summary. · `frontend/src/components/StatusBar.tsx`
- [Vite config](https://github.com/grim-sudo/busqueda/blob/main/frontend/vite.config.ts): build config · Frontend build-time configuration. · `frontend/vite.config.ts`

### Backend

Flask API, registry data, and internal simulation.

- [Flask API](https://github.com/grim-sudo/busqueda/blob/main/backend/app.py): web api · Main backend application exposing status, health, services, and search endpoints. · `backend/app.py`
- [Config](https://github.com/grim-sudo/busqueda/blob/main/backend/config.py): runtime config · Backend configuration and environment-sensitive values. · `backend/config.py`
- [Registry data](https://github.com/grim-sudo/busqueda/blob/main/backend/fake_services.py): data source · Authoritative service inventory used by the API and UI. · `backend/fake_services.py`
- [Gitea sim](https://github.com/grim-sudo/busqueda/blob/main/backend/gitea_sim.py): internal service · In-container Gitea-like simulation supporting the lab narrative. · `backend/gitea_sim.py`
- [System check](https://github.com/grim-sudo/busqueda/blob/main/backend/scripts/system_check.py): diagnostic · Internal readiness and environment check utility. · `backend/scripts/system_check.py`

## Connections

- Browser → Nginx: HTTP · All browser traffic enters through the Nginx front door.
- Nginx → Index page: serve · Nginx serves the compiled SPA assets as static files.
- Nginx → Flask API: proxy /api · Application requests are forwarded to the Flask backend.
- Entrypoint → Nginx: start · Container bootstrap launches the proxy stack.
- Entrypoint → Flask API: start · Container bootstrap launches the Python backend.
- Dockerfile → Entrypoint: runtime image · The image assembles the final single-container runtime around the entrypoint.
- Dockerfile → Vite config: build frontend · Frontend assets are built during image creation.
- Index page → App bootstrap: load · The browser loads the SPA entry script from the HTML shell.
- App bootstrap → Dashboard: mount · React mounts the top-level dashboard.
- Dashboard → Search panel: compose · The dashboard includes search controls.
- Dashboard → Service table: compose · The dashboard includes the service registry view.
- Dashboard → Status bar: compose · The dashboard includes the status summary.
- Dashboard → Flask API: fetch data · The UI calls backend endpoints for status and registry data.
- Flask API → Config: reads · The API uses backend configuration to control runtime behavior.
- Flask API → Registry data: serves registry · The registry dataset is sourced from backend-local service definitions.
- Flask API → Gitea sim: internal sim · The backend exposes an internal Gitea-like simulation within the container boundary.
- Flask API → System check: diagnostics · The backend has an internal diagnostic/readiness path.