building-data-apps

# Building Data Applications Architect high-quality data dashboards and interactive reports. You MUST select the appropriate framework before implementation. ## Step 0: Framework Selection You MUST select the framework based on the user's maintenance requirements and data ecosystem. ### Choice: Streamlit - **User Profile**: Data Scientists / Python users. - **Logic Complexity**: High Python dependency (Pandas, NumPy, local data processing). - **Deployment**: Single-file Python script. - **Customization**: Standard layout (fast boilerplate). ### Choice: React + Vite - **User Profile**: Web Developers / Full-stack teams. - **Logic Complexity**: High UI and Interactivity requirements (e.g., drag-and-drop, interactive maps). - **Deployment**: Standalone Frontend + Backend API. - **Customization**: Infinite (Custom CSS, specialized JS libraries). ### Guidance: - **Check for existing stack first**: ALWAYS prefer the framework the user is already using in their project (e.g., if you see a `package.json` with React dependencies, use React; if you see existing Streamlit files, use Streamlit). - **Default to React + Vite** for production-grade applications that require complex client-side state, custom branding, or integration into a larger web ecosystem. - **Default to Streamlit** if the user specifically mentions "Python dashboard", needs to iterate on complex local Python data processing, or requires a single-script deployment. ## Step 1: Implementation Plan You MUST propose a plan to the user that specifies the chosen framework and justifies the choice based on the criteria above. -------------------------------------------------------------------------------- ## Shared Design Standards Regardless of framework, you MUST follow the principles in `references/shared_design_system.md`. - **Visual Style**: Minimal chrome, zinc color palette, and card-based layouts. - **Typography**: `DM Sans` for content, `JetBrains Mono` for data. -------------------------------------------------------------------------------- ## Framework Implementation ### If using Streamlit: 1. Read `references/streamlit_framework.md` for detailed CSS and component patterns. 2. Follow the "Checklist for New Dashboards" in that file. ### If using React + Vite: 1. Read `references/react_framework.md` for Tailwind and ECharts setup. 2. Follow the detailed component guidelines for KPI cards, Tables, and Panels. -------------------------------------------------------------------------------- ## AI Chat Interface (Optional Feature) ``` > [!IMPORTANT] > > If the user does not explicitly request a chat interface, you SHOULD > proactively ask them: "Would you like to include a Gemini-powered chat > interface to enable natural language queries against your data?" OR if > there is an implementation plan: "Would you like to include a > Gemini-powered chat interface to enable natural language queries against > your data? Let me know and I'll update the plan!". ``` If the user requests or agrees to the chat interface: ``` > [!CAUTION] > > Adding the chat interface is a significant change. Implicit approval of > the implementation plan for including the chat interface MUST never be > assumed. ``` 1. **Gather Technical Details**: You MUST read `references/chat_integration.md` for the technical requirements. 2. **Update the implementation plan**: If and only if there is an implementation plan, you MUST update the implementation plan. This is a significant change so the user must explicitly approve the updated plan. 3. **Verify Prerequisites**: Ensure the user has the Gemini Data Analytics API enabled and data exists in BigQuery. 4. **Reference Examples**: Adapt the patterns in `examples/react_chat_panel.jsx` and either `examples/fastapi_chat.py` or `examples/express_chat.ts`. ## Acceptance Criteria > [!CAUTION] > > If available, you MUST use browser testing capabilities (such as > `browser_subagent`, Puppeteer, Playwright, or an equivalent available tool) to > visually verify the frontend application is working correctly *before* > notifying the user that the task is complete. > [!IMPORTANT] > > The following checklist represents the strict requirements for this task. You > must include these items in whatever format you use to track your work (e.g., > your task list, implementation plan, or internal checklist). - [ ] Are CSS hover transitions smooth? - [ ] Are date fields formatted readably? (e.g., `MMM dd, yyyy`) - [ ] Do z-indexes stack correctly so dropdowns appear above table headers? (`relative z-30`) - [ ] Do all interactive form/button inputs handle loading/disabled states? - [ ] Is the application responsive and does the layout adapt well to different screen sizes? - [ ] Are API calls for data fetching successful, and is there appropriate error handling? - [ ] Does the dark mode toggle function correctly and apply styles consistently? - [ ] Do all visualizations render correctly and are they interactive where expected? - [ ] Is the dashboard visually appealing?