Skip to content

AGENTS.md

Latest commit

 

History

History
56 lines (43 loc) · 5.72 KB

AGENTS.md

File metadata and controls

56 lines (43 loc) · 5.72 KB
Raw

Developer & UI Architecture Guidelines

To maintain code hygiene, decoupling, and high scalability for future development, all engineering sessions must adhere to the structural principles defined in this document.

1. UI Theming & Styling Rules (Strictly No Hardcoding)

  • No Manual Brightness Switching: Avoid using Theme.of(context).brightness == Brightness.light within UI layout files to manually select light vs. dark colours. This causes visual inconsistencies and creates excessive styling coupling.
  • Use ThemeExtension: If a component needs custom colors (e.g. status chips, category badges) that do not natively map to the standard Material ColorScheme, declare them inside the custom EventHubThemeColors extension in lib/ui/theme/theme.dart.
  • Accessing Theme Extension: Retrieve these custom colors cleanly at the widget build level: 
    final themeColors = Theme.of(context).extension<EventHubThemeColors>();
// Use themeColors?.badgeBg, themeColors?.ticketValid, etc.

2. File and Directory Size Rules (Strictly No Monoliths)

  • No Large Files (> 300 Lines): Do not group multiple large visual classes (such as lists, comment blocks, modal sheets, and specific tabs) inside a single file. Keep files lean and single-purpose.
  • Component Splintering Directory Structure:
    • Tabs: Place major dashboard tabs (e.g., search feeds, tickets, nearby location feeds) under lib/ui/page/home/tabs/.
    • Widgets: Place reusable, domain-specific UI blocks (e.g. badges, custom button wrappers, sheets) under lib/ui/page/home/widgets/ or the global lib/widgets/ directory.
    • Coordinators: The coordinating view file (e.g., event_hub_home.dart) must act as a compact coordinator shell that only manages routing and state delegation, importing the modular widgets cleanly.

3. General Cleanliness and Coding Hygiene

  • Clean Directories: Avoid arbitrary folder names (such as newWidget/) and never leave active production elements inside /prototype.
  • Prefer Native Layouts Over Custom Helpers: Avoid creating custom responsive layout helpers (e.g. ad-hoc LayoutBuilder wrappers like _ResponsiveActionGroup, or custom downscaling button label classes) when native Flutter widgets such as OverflowBar, Wrap, or standard Text are fully available. Standard native components must always take precedence to ensure visual reliability and reduce code duplication.
  • No Unused Imports: Unused imports pollute the compilation namespace. Remove them systematically.
  • Verify Static Health: Always run Dart's static compiler check inside the terminal before finalising any sessions: 
    flutter analyze
    Ensure the command yields No issues found! with zero warnings or lints.

4. EventHub Product & Interaction Rules

  • Consistent Auth UI: Sign in, sign up, forgot password, and welcome/auth entry screens must use the same EventHub theme, card shape, inputs, buttons, and route animation style as the rest of the app. Do not reintroduce old grey pill fields or one-off auth layouts.
  • No Missing Asset Dependencies: Do not reference undeclared image assets such as assets/images/google_logo.png or assets/images/icon-480.png. Prefer themed Material icons unless an asset is present and registered in pubspec.yaml.
  • Safe Provider Access: Never call context.read, Provider.of, or inherited-widget lookups from dispose(). Cache required providers in didChangeDependencies() if cleanup needs them.
  • Explicit Navigation Actions: Cards that contain inspectable content such as QR codes should not navigate on the whole card tap. Use explicit buttons like View QR and Open Event.
  • Nearby Scan Controls: Nearby discovery must expose readable Start Scan Loop and Scan Once controls. While scanning, users must be able to stop the current scan/loop, and progress indicators must not overlap the event list.
  • Nearby Quick Preview: Nearby result taps should open a quick event summary sheet with actions for buying tickets and opening full details, rather than skipping directly to detail without context.
  • Organizer Is More Than Publish: Organizer mode should include management surfaces, not only a create-event form. Preserve and extend pages like Manage Events for organizer workflows.
  • Backend-First Data: Do not add frontend-only placeholder event data for missing production concepts. If the app needs categories, ticket types, seeded tickets, or richer event data, add them to the backend schema/API/seed first and then map them in Flutter.
  • Mode-Specific Navigation: Attendee and organizer are local app modes, not backend account roles. Keep registration account-only, show the mode chooser when no mode is selected, and let users switch modes from More. The bottom navigation should still render mode-specific workflows.
  • Organizer Event Management: Organizer event lists must be loaded from /api/organizations/{organizationId}/events, not public discovery data. Organizer cards should expose explicit actions for event detail, ticket management, editing, and cancellation/deletion.
  • Ticket Types Belong to Backend Events: Adding tickets must call the backend ticket type API. Do not fake ticket types or attach frontend-only ticket data to public seed cards.
  • Auth Validation Must Be Human: Sign up/sign in forms should validate locally with TextFormField errors and should display concise backend error messages. Never surface raw Spring validation exception text in the UI.
  • Splash/Auth Consistency: Splash, welcome, sign in, sign up, and forgot password must use the EventHub theme colors, Material icons, shared auth shell, and shared route animation style. Avoid hardcoded white splash cards or undeclared logo assets.