diff --git a/architect/02-design/README.md b/architect/02-design/README.md deleted file mode 100644 index 6c972cc..0000000 --- a/architect/02-design/README.md +++ /dev/null @@ -1,184 +0,0 @@ -# TaskFlow Architecture Design - -**Purpose:** Technical architecture and visual representation of TaskFlow system -**Audience:** Sam (project lead), Frontend/Backend developers, QA team -**Scope:** System boundaries, component structure, data model, deployment strategy -**Last Updated:** 2024-09-05 -**Assumptions:** Small team scale (2-15 users), managed cloud deployment, modern browser support - -## Technical Diagrams - -### 1. System Context Diagram -**File:** `system-context.png` -**Purpose:** Shows TaskFlow's position in the overall ecosystem -**Audience:** All stakeholders -**Key Elements:** -- Team members (users) access via HTTPS through browsers -- TaskFlow core application handles task management -- Admin-managed authentication service (no self-registration) -- Clear boundary between internal task management and external user access - -**Key Assumptions:** -- Modern browser requirement (Chrome, Firefox, Safari, Edge) -- HTTPS-only access for security -- Admin controls user account creation and management - -### 2. Container Architecture Diagram -**File:** `container-architecture.png` -**Purpose:** Major technological building blocks and their interactions -**Audience:** Development team, technical stakeholders -**Key Elements:** -- Single Page Application (React/Vue) for responsive UI -- REST API backend with business logic and data validation -- Separate databases for task data and user accounts -- JSON API communication between frontend and backend -- SQL-based data persistence - -**Technology Decisions:** -- SPA architecture for responsive desktop/mobile experience -- REST API provides clean separation of concerns -- PostgreSQL for relational data integrity -- Separate user store emphasizes admin-controlled access - -### 3. Data Model Diagram -**File:** `data-model.png` -**Purpose:** Core entities, attributes, and relationships -**Audience:** Backend developers, database administrators -**Key Elements:** -- **USERS table:** Core user identity, admin flag, credentials -- **TASKS table:** Task data with status/priority enums, foreign key relationships -- **Relationships:** Users can be assigned tasks and create tasks (many-to-many via foreign keys) - -**Design Decisions:** -- Simple two-table model reflects focused scope (no complex workflows) -- Enum fields for status (Open/In Progress/Blocked) and priority (Low/Medium/High) -- Audit trails via created_at/updated_at timestamps -- Foreign key constraints ensure data integrity - -### 4. Deployment View Diagram -**File:** `deployment-view.png` -**Purpose:** Infrastructure layout and scalability approach -**Audience:** DevOps, deployment team, infrastructure planning -**Key Elements:** -- Load balancer (ALB) routes traffic to appropriate tiers -- Web tier serves static assets (React build artifacts) -- Application tier runs REST API servers with auto-scaling -- Data tier uses managed PostgreSQL with automated backups -- Clear separation of stateless (web/app) and stateful (database) components - -**Platform-Agnostic Decisions:** -- Standard 3-tier architecture works on any cloud provider -- Managed services reduce operational overhead -- Auto-scaling groups handle variable load -- Automated backups protect against data loss - -## 3D Isometric Visual - -### TaskFlow Architecture Overview -**File:** `taskflow-3d-architecture.png` -**Purpose:** Engaging visual representation for stakeholder communication -**Audience:** Non-technical stakeholders, presentations, documentation -**Key Elements:** -- Team members with computers showing real usage context -- Load balancer managing traffic distribution -- Multiple React frontend instances for availability -- API server cluster handling business logic -- PostgreSQL database as the foundation - -**Visual Design Principles:** -- Clean isometric perspective shows relationships clearly -- Color coding: Blue (users/frontend), Orange (API/processing), Green (database/storage) -- Flow arrows indicate data movement through the system -- Human figures emphasize the user-centric nature of the system - -## Architecture Decision Records (ADRs) - -### ADR-001: Single Page Application Architecture -**Context:** Need responsive web interface that works on desktop and mobile -**Decision:** Build React/Vue SPA with responsive design -**Consequences:** -- ✅ Single codebase for all screen sizes -- ✅ Modern, fast user experience -- ❌ Requires JavaScript enabled -- ❌ Initial bundle size consideration - -**Alternatives Rejected:** -- Server-rendered pages (slower interactions) -- Separate mobile app (out of scope) - -### ADR-002: REST API Backend -**Context:** Need clean separation between UI and business logic -**Decision:** JSON REST API with clear CRUD operations -**Consequences:** -- ✅ Platform-agnostic API design -- ✅ Easy testing and development -- ✅ Future integration possibilities -- ❌ Multiple round trips for complex operations - -**Alternatives Rejected:** -- GraphQL (overkill for simple CRUD) -- Server-side rendering (couples UI and API) - -### ADR-003: PostgreSQL for Data Persistence -**Context:** Need reliable data storage with referential integrity -**Decision:** PostgreSQL as primary database -**Consequences:** -- ✅ ACID transactions prevent data loss -- ✅ Foreign key constraints ensure consistency -- ✅ Mature ecosystem and tooling -- ❌ Requires database administration knowledge - -**Alternatives Rejected:** -- NoSQL (unnecessary for relational data) -- SQLite (insufficient for multi-user access) - -### ADR-004: Admin-Controlled User Management -**Context:** Security requirement, no self-registration -**Decision:** All user accounts created by administrators -**Consequences:** -- ✅ Controlled access and security -- ✅ Simplified onboarding process -- ❌ Administrative overhead for user creation -- ❌ Cannot scale to public access - -**Alternatives Rejected:** -- Self-registration (security risk) -- External SSO (adds complexity) - -## Risk Assessment - -### Technical Risks -- **Medium:** Single database could become bottleneck (mitigation: read replicas) -- **Low:** Browser compatibility issues (mitigation: modern browser requirement) -- **Low:** API rate limiting needs (mitigation: reasonable user scale assumption) - -### Security Risks -- **High:** Password storage security (mitigation: bcrypt hashing, never plain text) -- **Medium:** Session management (mitigation: secure tokens, HTTPS only) -- **Low:** SQL injection (mitigation: parameterized queries, ORM usage) - -### Operational Risks -- **Medium:** Database backup and recovery (mitigation: automated backups, tested restore procedures) -- **Low:** Application server failures (mitigation: auto-scaling, health checks) - -## Quality Attribute Scenarios - -### Performance -- **Scenario:** User creates task and assigns to team member -- **Response:** Task appears in assignee's list within 2 seconds -- **Measure:** 95th percentile response time ≤ 2000ms - -### Availability -- **Scenario:** Primary API server fails during business hours -- **Response:** Load balancer routes to healthy server automatically -- **Measure:** Service continues with <30 second disruption - -### Security -- **Scenario:** User attempts to access tasks not assigned to them -- **Response:** System denies access and logs attempt -- **Measure:** Zero unauthorized data access incidents - -### Usability -- **Scenario:** New user completes task creation workflow -- **Response:** Task created successfully in ≤3 steps -- **Measure:** 90% of test users complete without assistance \ No newline at end of file