BridgeStack

API backend bridging OpenStacks data layers.

The API layer for OpenStacks — connecting database to frontend.

---

Quick Start

git clone https://github.com/Varnasr/BridgeStack.git
cd BridgeStack
pip install -r requirements.txt
uvicorn app.main:app --reload

Open http://localhost:8000/docs for interactive API docs.

With Docker

docker compose up --build

With Make

make dev       # install with dev tools
make run       # start the server
make test      # run tests with coverage
make check     # lint + test

Architecture

RootStack (SQLite) → BridgeStack (FastAPI) → ViewStack / EquityStack / FieldStack

BridgeStack serves as the middleware connecting RootStack data to all consumer Stacks:

Stack	Role	Connection
RootStack	SQLite schemas & seed data	Data source
BridgeStack (this repo)	REST API (FastAPI)	You are here
ViewStack	Frontend dashboards	Consumes API
EquityStack	Python analysis workflows	Consumes API
FieldStack	R fieldwork tools	Consumes API
InsightStack	MEL tools	Consumes API
SignalStack	Curated content	Consumes API

API Endpoints

All endpoints are prefixed with /api/v1. Full reference: docs/api-reference.md

Domain	Endpoints	Filters
Geography	states, districts	region, state_id, tier
Sectors	sectors	—
Indicators	indicators, values	sector_id, source, state_id, year
Policies	schemes, budgets, coverage	sector_id, status, level, fiscal_year
Tools	tools	stack, language, tool_type, difficulty
Health	/, /health	—

Documentation

Full documentation is in the docs/ directory:

• Getting Started — Installation and first request
• API Reference — Complete endpoint docs
• Architecture — System design and data model
• Configuration — Environment variables
• Deployment — Docker, production, monitoring

Configuration

Environment variables (prefix BRIDGE_):

Variable	Default	Description
BRIDGE_DATABASE_URL	sqlite:///./rootstack.db	Database connection string
BRIDGE_DEBUG	false	Enable debug mode
BRIDGE_CORS_ORIGINS	["*"]	Allowed CORS origins
BRIDGE_LOG_LEVEL	INFO	Logging level

See .env.example for a starter configuration.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest --cov=app

# Lint & format
ruff check .
ruff format .

Project Structure

BridgeStack/
├── app/
│   ├── main.py              # FastAPI app entry point
│   ├── core/
│   │   ├── config.py        # Settings (env-configurable)
│   │   └── database.py      # SQLAlchemy setup
│   ├── models/              # SQLAlchemy ORM models
│   ├── schemas/             # Pydantic response schemas
│   └── routes/              # API route handlers
├── tests/                   # Pytest test suite
├── docs/                    # Project documentation
├── pyproject.toml           # Project metadata & tool config
├── requirements.txt         # Python dependencies
├── Makefile                 # Development commands
├── Dockerfile               # Container image
└── docker-compose.yml       # Local orchestration

Contributing

See CONTRIBUTING.md for guidelines. Areas where contributions are welcome:

• Additional query endpoints and aggregations
• Pagination and rate limiting
• Response caching
• PostgreSQL adapter
• WebSocket support for real-time data

Please read our Code of Conduct before participating.

License

MIT — free to use, modify, and share. See LICENSE.

---

Created by Varna Sri Raman — Development Economist & Social Researcher

Part of the OpenStacks ecosystem by ImpactMojo.