Adamastor

Track Portuguese Parliament performance with transparency.

What is this?

Adamastor collects public data from the Portuguese Parliament and calculates performance metrics for each deputy:

• Proposals - Bills and legislative initiatives authored
• Interventions - Speeches and participation in debates
• Attendance - Presence at plenary meetings
• Questions - Parliamentary questions submitted

Each deputy gets a Work Score and letter grade (A-F) based on their activity compared to the average.

Note: This project measures activity, not ideology. We don't rate deputies on their political positions.

---

Quick Start

# Prerequisites: Bun, Docker

git clone https://github.com/bcamarneiro/adamastor.git
cd adamastor
bun install

# Start local database
npx supabase start

# Run the web app
bun dev

Open http://localhost:3000

To populate with data, see CONTRIBUTING.md.

---

Documentation

Document	What it covers
ARCHITECTURE.md	How the system works - data flow, transforms, database
CONTRIBUTING.md	Setup guide, development workflow, how to contribute
TESTING.md	How to test the platform and report bugs
docs/AI_AGENTS.md	Guidelines for AI agents and AI-assisted development

---

Project Structure

adamastor/
├── apps/
│   ├── watcher/     # Data pipeline - fetches & transforms Parliament data
│   └── web/         # React frontend - displays deputy performance
├── packages/
│   └── shared/      # Shared TypeScript types
└── supabase/        # Database migrations and seed data

How the pieces fit together

Parliament API  ──→  Watcher  ──→  Supabase  ──→  Web App  ──→  Browser
(public data)      (daily job)    (database)    (React)       (you)

Watcher runs daily via GitHub Actions, fetching Parliament data and transforming it. Web is a React app that reads from Supabase and displays deputy performance.

---

Features

Feature	Description
Report Card	Enter your postal code → see your deputies' grades
Rankings	National and district leaderboards
Battle	Compare two deputies head-to-head
Waste Calculator	See the cost of underperformance

---

Tech Stack

Layer	Technology
Runtime	Bun
Frontend	React 19, Vite, Tailwind CSS v4
Database	Supabase (PostgreSQL)
Pipeline	GitHub Actions
Hosting	Vercel

---

Data Sources

All data comes from official Parliament sources:

• Open Data API (deputies, initiatives, activities)
• Parliament website (attendance, biographies - scraped)

Data updates daily at 06:00 UTC.

---

Political Neutrality

This project is non-partisan. We measure activity metrics only:

✓ How many proposals a deputy authored ✓ How many times they spoke in Parliament ✓ Whether they attended plenary sessions

✗ We do not rate political positions ✗ We do not endorse any party

---

Help Us Test

Want to help improve Adamastor? No coding required!

We're looking for testers to explore the platform and report bugs, UX issues, or suggest improvements.

👉 Start Testing - Complete guide in Portuguese

What to test:

• Desktop & mobile experience
• All pages (Rankings, Battle Royale, Deputy Profiles, etc.)
• Report anything confusing or broken

Where to report:

• 🐛 Bug reports
• 💡 Suggestions
• ❓ Questions

---

Contributing Code

1. Fork the repo
2. Create branch from staging: git checkout -b fix/my-fix
3. Make changes, test locally (bun dev)
4. Submit PR to staging

See CONTRIBUTING.md for detailed setup.

Working with AI Agents

This repository is optimized for AI collaboration (Cursor, GitHub Copilot, Claude Code). See docs/AI_AGENTS.md for:

• Guidelines for AI-assisted development
• Best practices for writing prompts
• Monorepo-specific patterns
• Testing and code quality standards

---

License

MIT