geutebruck/geutebruck-api/specs/001-flutter-app

Flutter App Specification - 001-flutter-app

Overview

This specification defines a mobile application for managing Geutebruck video surveillance systems through the REST API. The app provides administrators and operators with full control over server configurations, action mappings, cameras, monitors, and cross-switching operations.

Specification Documents

📜 constitution.md

Foundational principles and standards

Defines the core principles, architecture patterns, testing standards, and code quality requirements for the Flutter app development. This document must be reviewed and understood by all team members before beginning implementation.

Key Topics:

• Clean Architecture + BLoC pattern
• Testing requirements (80% coverage minimum)
• Security standards (secure storage, HTTPS, token management)
• Performance budgets
• Code organization and style guidelines

---

📋 spec.md

Functional requirements and user stories

Contains all user stories organized by epic, with detailed acceptance criteria for each feature. This is the primary reference for understanding WHAT needs to be built and HOW it should behave from a user perspective.

Epics Covered:

1. Authentication & Authorization (3 user stories)
2. Server Management (8 user stories)
3. Action Mapping Management (5 user stories)
4. Camera Management (3 user stories)
5. Monitor Management (2 user stories)
6. Cross-Switching (2 user stories)
7. Configuration Management (2 user stories)
8. User Interface & Navigation (4 user stories)

Total: 29 user stories with complete acceptance criteria

---

🏗️ plan.md

Technical implementation strategy

Describes the technical architecture, technology stack, design patterns, and implementation approach. This document explains HOW the system will be built from a technical perspective.

Key Sections:

• Technology stack with justifications
• Clean Architecture layered approach
• BLoC state management pattern
• Folder structure and organization
• API integration strategy
• Caching and offline support
• Error handling patterns
• Testing strategy
• Performance optimization techniques

---

✅ tasks.md

Detailed implementation task breakdown

Provides a comprehensive, ordered list of implementation tasks organized by user story and phase. Each task includes file paths, dependencies, and test requirements.

Phases:

1. Foundation & Setup
2. Server Management
3. Action Mapping Management
4. Camera Management
5. Monitor & Cross-Switching
6. Configuration Management
7. UI & Navigation
8. Testing & Polish
9. Deployment Preparation

Total: 186+ tasks with dependencies mapped

---

🚀 quickstart.md

Setup and running instructions

Step-by-step guide for setting up the development environment, installing dependencies, running the app, and common development workflows.

Covers:

• Prerequisites and installation
• Running the app on different platforms
• Development workflow
• Testing commands
• Troubleshooting
• IDE setup
• CI/CD configuration

---

Getting Started

For Product Owners / Stakeholders

1. Start with spec.md to review user stories and acceptance criteria
2. Use constitution.md to understand quality standards
3. Review plan.md for technical approach and timeline estimates

For Developers

1. Read constitution.md to understand coding standards
2. Study plan.md for architecture and patterns
3. Follow quickstart.md to set up your environment
4. Use tasks.md to pick up tasks based on current phase
5. Reference spec.md for acceptance criteria while implementing

For Project Managers

1. Use tasks.md for sprint planning and task assignment
2. Track progress against user stories in spec.md
3. Monitor adherence to constitution.md standards during code review
4. Reference plan.md for understanding technical dependencies

Document Relationships

┌─────────────────┐
│ constitution.md │ ◄─── Defines standards for all documents
└─────────────────┘
         │
         ▼
┌─────────────────┐
│    spec.md      │ ◄─── What needs to be built (User Stories)
└─────────────────┘
         │
         ▼
┌─────────────────┐
│    plan.md      │ ◄─── How it will be built (Architecture)
└─────────────────┘
         │
         ▼
┌─────────────────┐
│   tasks.md      │ ◄─── Detailed task breakdown
└─────────────────┘
         │
         ▼
┌─────────────────┐
│ quickstart.md   │ ◄─── How to get started
└─────────────────┘

Current Status

Specification Status: ✅ Complete

All specification documents have been created and reviewed. Ready for implementation.

Implementation Status: 🚧 Not Started

Awaiting Flutter SDK installation completion and development environment setup.

Implementation Workflow

Following the spec-kit methodology:

1. Constitution (Standards)     ✅ Complete
2. Specification (Requirements) ✅ Complete
3. Clarification (Q&A)          ⏳ Ongoing
4. Plan (Architecture)          ✅ Complete
5. Tasks (Breakdown)            ✅ Complete
6. Implementation               🚧 Ready to start

API Reference

The Flutter app integrates with the Geutebruck REST API:

Base URL: http://localhost:8000/api/v1

Key Endpoints:

• Authentication: /auth/login, /auth/refresh
• Servers: /configuration/servers/gcore, /configuration/servers/geviscope
• Action Mappings: /configuration/action-mappings
• Cameras: /cameras
• Monitors: /monitors
• Cross-Switching: /crossswitch

See the API documentation at http://localhost:8000/docs for complete endpoint details.

Technology Stack Summary

• Framework: Flutter 3.24+
• Language: Dart 3.0+
• State Management: BLoC (flutter_bloc)
• HTTP Client: Dio + Retrofit
• Local Storage: Hive + flutter_secure_storage
• Dependency Injection: get_it + injectable
• Code Generation: freezed, json_serializable, build_runner
• Testing: mockito, bloc_test, integration_test

Success Criteria

The implementation will be considered successful when:

• All 29 user stories implemented with acceptance criteria met
• Test coverage ≥ 80%
• All widget tests passing
• Integration tests for critical flows passing
• Performance benchmarks met (startup < 3s, 60 FPS scrolling)
• Security review completed
• Accessibility tested
• User acceptance testing completed

Timeline Estimate

Based on the task breakdown in tasks.md:

• Phase 1 (Foundation): 1-2 weeks
• Phase 2 (Server Management): 1-2 weeks
• Phase 3 (Action Mappings): 1-2 weeks
• Phase 4 (Cameras): 1-2 weeks
• Phase 5 (Monitors & Cross-Switching): 1-2 weeks
• Phase 6 (Configuration): 1 week
• Phase 7 (UI & Navigation): 1 week
• Phase 8 (Testing & Polish): 2 weeks
• Phase 9 (Deployment): 1 week

Total: 10-13 weeks (2.5-3 months) with 2-3 developers

Team Roles

Recommended Team:

• 1 Senior Flutter Developer (Architecture, Code Review)
• 2 Flutter Developers (Feature Implementation)
• 1 QA Engineer (Testing)
• 1 UI/UX Designer (Designs and Assets)
• 1 Product Owner (Requirements, Acceptance)

Maintenance & Updates

This specification is a living document. Updates should be made when:

• New features are requested
• Technical architecture changes
• API endpoints are modified
• User feedback requires adjustments

Version Control:

• All changes tracked in Git
• Each major update creates a new version tag
• Breaking changes documented in CHANGELOG.md

Questions or Clarifications

For questions about the specification:

1. Check the relevant document (constitution, spec, plan, tasks)
2. Review the quickstart guide for setup/development questions
3. Consult the team lead for architectural decisions
4. Create an issue in the project repository for tracking

License

This specification is proprietary to the Geutebruck API project.

---

Specification Version: 1.0 Last Updated: December 19, 2025 Status: Ready for Implementation