AI-powered analysis of Argentina's open government data
Ask questions in natural language. Get answers with charts, tables, and verified sources.
OpenArg is an open-source platform that lets users query Argentina's public datasets through a conversational AI interface. A multi-agent pipeline plans the query, fetches data from official government APIs and CKAN portals, analyzes the results, and responds with markdown, interactive charts, and links to original sources. The frontend is a Next.js application that consumes SSE streams from a Python/FastAPI backend.
The system runs as two containerized services behind a Caddy reverse proxy on EC2: this Next.js frontend and a FastAPI backend with PostgreSQL (pgvector), Redis, and Celery workers.
When a user submits a question, the backend orchestrates a multi-agent pipeline and streams real-time progress to the frontend via SSE (Server-Sent Events). All agent logic runs on the backend; the frontend is a consumer that visualizes each agent's progress as it happens.
| Agent | Role | Visible in UI as |
|---|---|---|
| Strategist | Interprets the question, selects data sources, generates execution plan | "Estratega" |
| Researchers | Execute the plan in parallel — query APIs, run SQL, search vector indexes | "Investigadores" |
| Analyst | Analyze collected data, generate insights with citations and charts | "Analista" |
| Policy Analyst | Evaluate public policy using DNFCG criteria (pertinence, efficacy, efficiency, impact, sustainability) | "Deep Policy Analysis" toggle |
| Writer | Compose the final response, format markdown, suggest follow-ups | "Redactor" |
The frontend renders each agent's activity in real-time via the AgentActivityBar component, showing the user which phase is active. The frontend does not run any agent logic itself — it subscribes to the backend's SSE stream and updates the UI accordingly.
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| UI | React 19, Motion |
| Language | TypeScript 5 |
| Charts | Recharts 3, Observable Plot |
| Auth | NextAuth 4 (Google OAuth) |
| Styling | Custom CSS dark theme (glassmorphism, Argentina flag palette) |
| Internationalization | next-intl |
| Monitoring | Sentry |
| Testing | Vitest, Testing Library |
| Deploy | Docker on EC2 (GHCR images, Caddy reverse proxy) |
git clone https://github.com/colossus-lab/openarg_frontend.git
cd openarg_frontend
cp .env.local.example .env.local # fill in required values
docker build -t openarg-frontend .
docker run -p 3000:3000 --env-file .env.local openarg-frontendgit clone https://github.com/colossus-lab/openarg_frontend.git
cd openarg_frontend
npm install
cp .env.local.example .env.local # fill in required values
npm run dev # http://localhost:3000Backend required: The frontend requires the OpenArg Backend running. Set
OPENARG_BACKEND_URLto point to your backend instance.
| Variable | Description |
|---|---|
OPENARG_BACKEND_URL |
Backend API base URL (default: http://localhost:8081) |
OPENARG_BACKEND_API_KEY |
API key for authenticating with the backend |
NEXTAUTH_SECRET |
JWT signing secret (openssl rand -base64 32) |
NEXTAUTH_URL |
Auth callback URL (e.g. http://localhost:3000) |
GOOGLE_CLIENT_ID |
Google OAuth client ID |
GOOGLE_CLIENT_SECRET |
Google OAuth client secret |
ALLOWED_EMAILS |
Comma-separated list of allowed login emails |
ADMIN_EMAILS |
Comma-separated list of admin emails |
npm run dev # Start dev server (port 3000)
npm run build # Production build
npm run start # Start production server
npm run lint # ESLint
npm run test # Run tests (Vitest)
npm run test:watch # Run tests in watch modesrc/
├── app/
│ ├── api/
│ │ ├── auth/[...nextauth]/ # NextAuth Google OAuth
│ │ ├── chat/ # Main SSE orchestrator (POST)
│ │ ├── conversations/ # Conversation CRUD
│ │ ├── datasets/ # Dataset listing
│ │ ├── feedback/ # User feedback
│ │ ├── taxonomy/ # Data taxonomy
│ │ ├── transparency/ # Transparency endpoint
│ │ └── users/ # User sync, settings, data export
│ ├── chat/page.tsx # Chat UI (SSE consumer)
│ ├── datasets/page.tsx # Dataset explorer
│ ├── login/page.tsx # Login page
│ └── layout.tsx # Root layout
├── components/
│ ├── AgentActivityBar.tsx # Pipeline phase visualization
│ ├── ChatMessage.tsx # Markdown + GFM renderer
│ ├── ConversationSidebar.tsx # Chat history sidebar
│ ├── DataChart.tsx # Recharts wrapper (line/bar/pie)
│ ├── ObservablePlotChart.tsx # Observable Plot charts
│ ├── SourcePanel.tsx # Collapsible data sources
│ ├── TaxonomyExplorer.tsx # Dataset taxonomy browser
│ └── ... # UI primitives, auth, dialogs
├── hooks/
│ ├── useSSEStream.ts # SSE connection management
│ ├── useConversationState.ts # Chat state management
│ └── useAutoResize.ts # Textarea auto-resize
├── i18n/ # Internationalization config
├── lib/
│ ├── authOptions.ts # NextAuth configuration
│ ├── logger.ts # Structured logging
│ ├── rateLimit.ts # API rate limiting
│ └── types.ts # Shared type definitions
└── middleware.ts # Route middleware
The backend repository contains detailed documentation on system architecture, deployment, API reference, and more:
| Document | Description |
|---|---|
| Architecture | System design and hexagonal architecture |
| API Reference | Backend REST API endpoints |
| Database Schema | PostgreSQL tables, pgvector indexes |
| Deployment | Docker Compose, EC2, Caddy setup |
| Data Sources | CKAN portals, APIs, scrapers |
| Query Pipeline | Multi-agent pipeline deep dive |
| Data Ingestion | Celery workers, download pipeline |
| Monitoring | Observability and health checks |
| Security | Auth, rate limiting, input validation |
| Contributing | Contribution guidelines |
| Changelog | Release history |
We welcome contributions! Please read our guidelines before getting started:
- Contributing Guide — Setup, workflow, PR process, and coding standards
- Code of Conduct — Expected behavior and community standards
- Security Policy — How to report vulnerabilities responsibly
Quick steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Commit your changes and run
npm run lint && npm run test - Open a pull request against
staging— the repo includes PR and issue templates to guide you
Please open an issue first for major changes to discuss the approach.
Created by Luciano Carreno & Dante De Agostino
ColossusLab