adamastor

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 22 Open GitHub ↗

Portuguese Parliament transparency platform - watching over government performance

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Adamastor

> Track Portuguese Parliament performance with transparency.

[![CI](https://github.com/bcamarneiro/adamastor/actions/workflows/ci.yml/badge.svg)](https://github.com/bcamarneiro/adamastor/actions/workflows/ci.yml)

## 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

```bash
# 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](CONTRIBUTING.md#running-the-full-pipeline-locally).

---

## Documentation

| Document | What it covers |
|----------|----------------|
| **[ARCHITECTURE.md](ARCHITECTURE.md)** | How the system works - data flow, transforms, database |
| **[CONTRIBUTING.md](CONTRIBUTING.md)** | Setup guide, development workflow, how to contribute |
| **[TESTING.md](TESTING.md)** | How to test the platform and report bugs |
| **[docs/AI_AGENTS.md](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](https://bun.sh) |
| Frontend | React 19, Vite, Tailwind CSS v4 |
| Database | [Supabase](https://supabase.com) (PostgreSQL) |
| Pipeline | GitHub Actions |
| Hosting | Vercel |

---

## Data Sources

All data comes from official Parliament sources:

- [Open Data API](https://www.parlamento.pt/Cidadania/Paginas/DadosAbertos.aspx) (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](https://github.com/bcamarneiro/adamastor/discussions/203)** - 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](https://github.com/bcamarneiro/adamastor/discussions/new?category=testing-pagina-inicial)
- 💡 [Suggestions](https://github.com/bcamarneiro/adamastor/discussions/new?category=sugestoes)
- ❓ [Questions](https://github.com/bcamarneiro/adamastor/discussions/new?category=perguntas)

---

## 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](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](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

adamastor

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README