with one click
db-explorer-architect
// Architect and develop the DB Explorer project with Python backend and React frontend following hexagonal architecture
// Architect and develop the DB Explorer project with Python backend and React frontend following hexagonal architecture
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | db-explorer-architect |
| description | Architect and develop the DB Explorer project with Python backend and React frontend following hexagonal architecture |
Build and maintain a full-stack database exploration tool with:
This skill provides comprehensive workflows, coding standards, and tools for developing both backend and frontend components while preserving architectural boundaries.
db-explorer/
āāā README.md # Project overview and setup
āāā docker-compose.yml # Container orchestration
āāā .gitignore # Git ignore patterns
āāā .pre-commit-config.yaml # Pre-commit hooks
ā
āāā backend/ # Python Backend (FastAPI)
ā āāā pyproject.toml # Poetry dependencies and config
ā āāā poetry.lock # Locked dependencies
ā āāā pytest.ini # Pytest configuration
ā āāā .env.example # Environment variables template
ā ā
ā āāā src/ # Source code
ā ā āāā main.py # FastAPI application entry point
ā ā āāā config.py # Application configuration
ā ā ā
ā ā āāā core/ # Domain Layer (Pure Python, no external deps)
ā ā ā āāā domain/ # Domain models and types
ā ā ā ā āāā types.py # UniversalDataType, value objects
ā ā ā ā āāā models.py # Domain entities
ā ā ā āāā ports/ # Port interfaces
ā ā ā āāā database.py # DatabasePort interface
ā ā ā
ā ā āāā application/ # Application Layer (Use Cases)
ā ā ā āāā query_executor.py # Query execution service
ā ā ā āāā schema_reader.py # Schema reading service
ā ā ā
ā ā āāā adapters/ # Adapters Layer (External dependencies)
ā ā āāā driving/ # Driving adapters (API, CLI)
ā ā ā āāā api/
ā ā ā āāā v1/ # FastAPI routes
ā ā ā āāā queries.py
ā ā ā āāā schemas.py
ā ā ā
ā ā āāā driven/ # Driven adapters (Database connectors)
ā ā āāā oracle.py # Oracle connector
ā ā āāā clickhouse.py # ClickHouse connector
ā ā āāā databricks.py # Databricks connector
ā ā āāā factory.py # Connector factory
ā ā
ā āāā tests/ # Test suite
ā āāā conftest.py # Pytest fixtures
ā āāā unit/ # Unit tests
ā āāā integration/ # Integration tests
ā āāā test_data/ # Test fixtures and data
ā
āāā web-ui/ # React TypeScript Frontend
ā āāā package.json # npm dependencies
ā āāā tsconfig.json # TypeScript configuration
ā āāā vite.config.ts # Vite build configuration
ā āāā .env.example # Environment variables template
ā āāā index.html # HTML entry point
ā āāā public/ # Static assets
ā ā
ā āāā src/ # Source code
ā āāā main.tsx # React entry point
ā āāā App.tsx # Root component
ā āāā vite-env.d.ts # Vite type definitions
ā ā
ā āāā components/ # React components
ā ā āāā QueryEditor/ # SQL editor component
ā ā āāā SchemaExplorer/ # Schema browser component
ā ā āāā ResultsTable/ # Results display component
ā ā
ā āāā hooks/ # Custom React hooks
ā ā āāā useQuery.ts # Query execution hook
ā ā āāā useSchema.ts # Schema fetching hook
ā ā
ā āāā services/ # API service layer
ā ā āāā api.ts # Axios client setup
ā ā āāā queryService.ts # Query API calls
ā ā āāā schemaService.ts # Schema API calls
ā ā
ā āāā types/ # TypeScript type definitions
ā ā āāā query.ts # Query-related types
ā ā āāā schema.ts # Schema-related types
ā ā
ā āāā utils/ # Utility functions
ā āāā styles/ # Global styles
ā
āāā skills/ # Claude Code skills
āāā agent-architect/ # General agent skill
āāā db-explorer-architect/ # This skill
āāā SKILL.md # Main skill documentation
āāā scripts/ # Automation scripts
ā āāā lint_backend.sh # Backend code quality
ā āāā lint_frontend.sh # Frontend code quality
āāā references/ # Reference documentation
āāā architecture.md # Architecture rules
āāā design-patterns.md # Design patterns
āāā python-standards.md # Python coding standards
āāā react-standards.md # React coding standards
Location: All Python code resides in the backend/ directory.
Entry Point: backend/src/main.py - FastAPI application
Architecture: Hexagonal (Ports & Adapters)
src/core/domain): Pure Python, zero external dependenciessrc/core/ports): Abstract interfaces (e.g., DatabasePort)src/application): Use cases orchestrating domain logic, including the CleaningEnginesrc/adapters): External integrations (FastAPI, databases)Data Flow (fetch ā clean ā serve):
API (FastAPI) ā DataService ā CleaningEngine ā DatabasePort ā Remote DB
DatabasePort fetches raw, unmodified rows from the remote database (read-only).CleaningEngine (src/application/cleaning_engine.py) transforms raw rows in memory:
NULL-like values.UniversalDataType values.Read-Only Enforcement:
DatabasePort implementation must use a read-only connection (e.g., SET TRANSACTION READ ONLY, readonly=True driver option, or a DB user with SELECT-only privileges).execute_safe_read method must parse the SQL statement and raise ReadOnlyViolationError if it detects INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, or MERGE keywords before sending the query to the database.Adding New Database Connector:
backend/src/adapters/driven/[db-name].pyDatabasePort interface from src/core/ports/database.py; enforce read-only mode in connect().backend/src/adapters/driven/factory.pybackend/tests/integration/test_[db-name].pybackend/src/config.pyCode Quality Standards:
Configuration: backend/pyproject.toml
Commands (run from backend/ directory):
# Format code
black src/ tests/ --line-length 100
isort src/ tests/ --profile black
# Type check
mypy src/ --strict
# Lint
ruff check src/ tests/
# Test
pytest tests/ --cov=src --cov-report=term-missing
# All checks
../skills/db-explorer-architect/scripts/lint_backend.sh --fix
Location: All React code resides in the web-ui/ directory.
Entry Point: web-ui/src/main.tsx - React application root
Technology Stack:
Code Quality Standards:
Configuration: web-ui/tsconfig.json, web-ui/vite.config.ts
Commands (run from web-ui/ directory):
# Development server
npm run dev
# Lint
npm run lint # Check
npm run lint:fix # Auto-fix
# Format
npm run format # Fix formatting
npm run format:check # Check formatting
# Type check
npm run type-check
# Test
npm run test # Watch mode
npm run test:run # Single run
# Build
npm run build
# All checks
../skills/db-explorer-architect/scripts/lint_frontend.sh --fix
Adding New React Component:
web-ui/src/components/[ComponentName]/[ComponentName].tsx - Component implementation[ComponentName].module.css - Styles (optional)[ComponentName].test.tsx - Testsindex.ts - Barrel exportreferences/react-standards.md)Users can configure how fetched data is displayed and cleaned without touching the remote database. All rules are applied client-side or by the CleaningEngine in the backend.
Supported cleaning / view rules (examples):
NULL / empty are excluded from the displayed result set.TIMESTAMP / date columns are converted to ISO-8601 (YYYY-MM-DDTHH:mm:ssZ) before display.UniversalDataType when the connector returns an ambiguous type.How rules are applied (backend flow):
CleaningConfig alongside the SQL query.DataService forwards raw rows from DatabasePort to CleaningEngine.apply(rows, config).CleaningEngine applies each enabled rule in order and returns the cleaned List[UniversalRow].Frontend contract: the frontend always receives a UniversalFormat response ā a list of objects with { column: string, type: UniversalDataType, value: any } entries ā regardless of the source database.
Docker Setup:
docker-compose.yml at project rootEnvironment Configuration:
backend/.env (copied from .env.example)
DATABASE_URL=oracle://user:pass@host:port/service
LOG_LEVEL=INFO
CORS_ORIGINS=http://localhost:5173
web-ui/.env (copied from .env.example)
VITE_API_BASE_URL=http://localhost:8000/api/v1
API Communication:
http://localhost:8000/api/v1backend/src/main.py:
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:5173"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
Deployment:
# Development
docker-compose up -d
# Backend only
cd backend && uvicorn src.main:app --reload
# Frontend only
cd web-ui && npm run dev
See references/python-standards.md for complete Python coding standards.
See references/react-standards.md for complete React/TypeScript coding standards.
See references/design-patterns.md for detailed pattern implementations.
scripts/lint_backend.sh: Run all backend quality checks
./skills/db-explorer-architect/scripts/lint_backend.sh [--fix]
Runs: Black, isort, Mypy, Ruff, Pytestscripts/lint_frontend.sh: Run all frontend quality checks
./skills/db-explorer-architect/scripts/lint_frontend.sh [--fix]
Runs: Prettier, ESLint, TypeScript check, Vitestscripts/test_all.sh: Run all tests (backend + frontend)scripts/docker_dev.sh: Start development environment with DockerComprehensive documentation for architecture, patterns, and coding standards:
references/architecture.md: Hexagonal architecture rules, layer dependencies, DatabasePort interface contract, streaming & transport requirements, security & secrets managementreferences/python-standards.md: Python coding standards including:
references/react-standards.md: React/TypeScript coding standards including:
references/design-patterns.md: Design pattern implementations:
Create Adapter (backend/src/adapters/driven/[db-name].py):
from src.core.ports.database import DatabasePort
class MyDBConnector(DatabasePort):
def connect(self) -> None: ...
def execute_query_stream(self, sql: str, params=None): ...
def fetch_schema(self, table: str): ...
Register in Factory (backend/src/adapters/driven/factory.py):
CONNECTORS = {
"mydb": MyDBConnector,
# ... other connectors
}
Add Configuration (backend/src/config.py):
class MyDBConfig(BaseModel):
host: str
port: int = 5432
database: str
Write Tests (backend/tests/integration/test_mydb.py):
def test_mydb_connection():
connector = MyDBConnector(config)
connector.connect()
assert connector.is_connected()
Define Route (backend/src/adapters/driving/api/v1/[resource].py):
@router.post("/queries/execute")
async def execute_query(request: QueryRequest):
result = query_executor.execute(request.sql)
return {"data": result}
Frontend Service (web-ui/src/services/queryService.ts):
export const executeQuery = async (sql: string): Promise<QueryResult> => {
const response = await api.post('/queries/execute', { sql });
return response.data;
};
React Hook (web-ui/src/hooks/useQuery.ts):
export const useQuery = () => {
const [data, setData] = useState<QueryResult | null>(null);
const execute = useCallback(async (sql: string) => {
const result = await executeQuery(sql);
setData(result);
}, []);
return { data, execute };
};
Create Component Directory:
web-ui/src/components/MyComponent/
āāā MyComponent.tsx
āāā MyComponent.module.css
āāā MyComponent.test.tsx
āāā index.ts
Implement Component (MyComponent.tsx):
import React from 'react';
import styles from './MyComponent.module.css';
interface MyComponentProps {
title: string;
onAction: () => void;
}
export const MyComponent: React.FC<MyComponentProps> = ({ title, onAction }) => {
return (
<div className={styles.container}>
<h2>{title}</h2>
<button onClick={onAction}>Action</button>
</div>
);
};
Add Tests (MyComponent.test.tsx):
import { render, screen, fireEvent } from '@testing-library/react';
import { MyComponent } from './MyComponent';
describe('MyComponent', () => {
it('calls onAction when button clicked', () => {
const mockAction = vi.fn();
render(<MyComponent title="Test" onAction={mockAction} />);
fireEvent.click(screen.getByRole('button'));
expect(mockAction).toHaveBeenCalled();
});
});
# Database Configuration
DATABASE_URL=oracle://user:password@host:1521/service
CLICKHOUSE_URL=http://localhost:8123
DATABRICKS_HOST=your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=your-token
# Application Configuration
LOG_LEVEL=INFO
ENVIRONMENT=development
SECRET_KEY=your-secret-key
# CORS Configuration
CORS_ORIGINS=http://localhost:5173,http://localhost:3000
# Security
MAX_QUERY_ROWS=10000
QUERY_TIMEOUT_SECONDS=300
# API Configuration
VITE_API_BASE_URL=http://localhost:8000/api/v1
# Feature Flags
VITE_ENABLE_QUERY_HISTORY=true
VITE_ENABLE_SCHEMA_EXPLORER=true
# Application Configuration
VITE_APP_TITLE=DB Explorer
VITE_MAX_RESULT_ROWS=1000
Clone Repository:
git clone https://github.com/your-org/db-explorer.git
cd db-explorer
Backend Setup:
cd backend
# Install Python 3.12+
# Install Poetry: https://python-poetry.org/docs/#installation
poetry install
cp .env.example .env
# Edit .env with your database credentials
# Run migrations (if applicable)
poetry run alembic upgrade head
# Start backend server
poetry run uvicorn src.main:app --reload
Frontend Setup:
cd web-ui
# Install Node.js 18+ and npm
npm install
cp .env.example .env
# Edit .env with your API URL
# Start development server
npm run dev
Access Application:
Create Feature Branch:
git checkout -b feature/your-feature-name
Make Changes: Follow coding standards for backend or frontend
Run Quality Checks:
# Backend
cd backend
../skills/db-explorer-architect/scripts/lint_backend.sh --fix
# Frontend
cd web-ui
../skills/db-explorer-architect/scripts/lint_frontend.sh --fix
Run Tests:
# Backend
cd backend && pytest tests/ -v
# Frontend
cd web-ui && npm run test:run
Commit and Push:
git add .
git commit -m "feat: add your feature"
git push origin feature/your-feature-name
Create Pull Request: Follow PR template guidelines