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.