# io8 System Architect Agent - Customized for This Project

## Project-Specific Instructions

```json
{
  "architecture": "\n\n# Architecture Document Update - Simple Notes Taking App\nGenerated: 2025-10-09T05:05:00Z\n\n## System Overview\nThe \"Simple Notes Taking App\" will be built as a **client-server application** consisting of a responsive web frontend (Single Page Application - SPA) and a RESTful API backend, supported by a persistent relational database. The core functionality revolves around CRUD (Create, Read, Update, Delete) operations for user notes. Future enhancements, such as user authentication, are considered in the design for scalability.\n\n## Architecture Pattern\n**Client-Server / N-Tier Architecture**\nThis pattern provides a clear separation of concerns, enabling independent development, deployment, and scaling of each component:\n-   **Presentation Tier (Frontend SPA):** Handles user interface and user interaction logic. Communicates with the Application Tier via RESTful API calls.\n-   **Application Tier (Backend RESTful API):** Contains the business logic, handles API requests, orchestrates data operations, and interacts with the Data Tier.\n-   **Data Tier (Database):** Responsible for persistent storage and retrieval of application data.\n\nThis separation enhances maintainability, testability, and allows for horizontal scaling of the backend API.\n\n## Component Design\n\n### Frontend (Angular SPA)\nBuilding upon the Angular context of the base project, the frontend will leverage a modular, component-based structure.\n\n-   **`AppModule`**: The root module, bootstrapping the application.\n-   **`CoreModule`**: (Imported once in `AppModule`) Provides singleton services (e.g., `HttpClient` for API interaction, global error handling, authentication service if implemented) and application-wide configurations.\n-   **`SharedModule`**: (Imported by feature modules) Contains reusable UI components (e.g., custom buttons, modals, loaders), directives, and pipes that do not depend on singleton services.\n-   **`NotesModule`**: A lazy-loaded feature module encapsulating all note-related functionality.\n    -   `NoteListComponent`: Displays a list of notes with titles and content previews.\n    -   `NoteDetailComponent`: Shows the full title and content of a single note.\n    -   `NoteFormComponent`: Used for creating new notes and editing existing ones.\n    -   `NotesService`: Handles API calls specific to notes (`GET`, `POST`, `PUT`, `DELETE`).\n-   **`AuthModule` (Stretch Goal):** A lazy-loaded feature module for user registration and login.\n    -   `RegisterComponent`, `LoginComponent`\n    -   `AuthService`: Handles user authentication API calls.\n\n### Backend (Python/Flask REST API)\nThe backend will follow a layered design for clarity and maintainability.\n\n-   **`app.py` (Main Application Entry):** Initializes Flask app, registers blueprints.\n-   **`blueprints/` (API Layer):** Organizes API endpoints (e.g., `notes_bp.py`, `auth_bp.py`).\n    -   **Controllers/Routes:** Handle incoming HTTP requests, perform input validation, call appropriate services, and return JSON responses.\n-   **`services/` (Service Layer):** Contains business logic for notes management and user authentication.\n    -   `note_service.py`: Implements CRUD logic for notes, interacting with the repository.\n    -   `auth_service.py`: (If implemented) Handles user registration, login, and password hashing.\n-   **`repositories/` (Data Access Layer):** Abstracts database interactions.\n    -   `note_repository.py`: Provides methods for `Note` entity persistence (e.g., `get_all`, `get_by_id`, `create`, `update`, `delete`).\n    -   `user_repository.py`: (If implemented) Provides methods for `User` entity persistence.\n-   **`models/` (Data Models):** Defines SQLAlchemy models for `Note` and `User` entities.\n-   **`utils/`:** Common utilities like error handlers, input validators, etc.\n\n## Data Architecture\n\n### Primary Database: PostgreSQL (Production), SQLite (Development)\n-   **Rationale:** PostgreSQL is chosen for its robustness, reliability, and advanced features suitable for production environments. SQLite offers a lightweight, file-based database ideal for local development and testing, simplifying setup.\n\n### Entity Relationship Diagram (Conceptual)\n\n```mermaid\nerDiagram\n    User {\n        INTEGER id PK\n        VARCHAR username UNIQUE\n        VARCHAR passwordHash\n        DATETIME createdAt\n    }\n    Note {\n        INTEGER id PK\n        VARCHAR title\n        TEXT content\n        DATETIME createdAt\n        DATETIME updatedAt\n        INTEGER userId FK \"User ||--o{ Note\"\n    }\n```\n\n### Entity Details\n-   **Note Entity:**\n    -   `id`: Primary Key, Integer, Auto-incrementing.\n    -   `title`: String (VARCHAR), max 100 characters, NOT NULL.\n    -   `content`: Text (TEXT), nullable.\n    -   `createdAt`: Timestamp (DATETIME), auto-generated on creation.\n    -   `updatedAt`: Timestamp (DATETIME), auto-updated on modification.\n    -   `userId`: Foreign Key to `User.id`, nullable initially, becomes NOT NULL if user authentication is enforced for all notes.\n\n-   **User Entity (Optional/Stretch Goal):**\n    -   `id`: Primary Key, Integer, Auto-incrementing.\n    -   `username`: String (VARCHAR), unique, NOT NULL.\n    -   `email`: String (VARCHAR), unique, nullable.\n    -   `passwordHash`: String (VARCHAR), NOT NULL (stores securely hashed passwords).\n    -   `createdAt`: Timestamp (DATETIME), auto-generated on creation.\n\n## API Design\n\n**API Base URL:** `/api/v1`\n**Data Format:** JSON\n\n### Notes Endpoints\n-   **`GET /api/v1/notes`**\n    -   **Description:** Retrieve a list of all notes.\n    -   **Response:** `200 OK` with `[{ \"id\": ..., \"title\": ..., \"content\": ..., \"createdAt\": ..., \"updatedAt\": ... }]`\n\n-   **`GET /api/v1/notes/{id}`**\n    -   **Description:** Retrieve a single note by its ID.\n    -   **Parameters:** `id` (path parameter, integer).\n    -   **Response:** `200 OK` with `{ \"id\": ..., \"title\": ..., \"content\": ..., \"createdAt\": ..., \"updatedAt\": ... }` or `404 Not Found` if note does not exist.\n\n-   **`POST /api/v1/notes`**\n    -   **Description:** Create a new note.\n    -   **Request Body:** `{ \"title\": \"string (required)\", \"content\": \"string (optional)\" }`\n    -   **Response:** `201 Created` with `{ \"id\": ..., \"title\": ..., \"content\": ..., \"createdAt\": ..., \"updatedAt\": ... }` or `400 Bad Request` for validation errors.\n\n-   **`PUT /api/v1/notes/{id}`**\n    -   **Description:** Update an existing note by its ID.\n    -   **Parameters:** `id` (path parameter, integer).\n    -   **Request Body:** `{ \"title\": \"string (required)\", \"content\": \"string (optional)\" }` (fields can be partial for patch semantics, but for simplicity, full update is assumed).\n    -   **Response:** `200 OK` with updated note or `404 Not Found`, `400 Bad Request`.\n\n-   **`DELETE /api/v1/notes/{id}`**\n    -   **Description:** Delete a note by its ID.\n    -   **Parameters:** `id` (path parameter, integer).\n    -   **Response:** `204 No Content` on success, `404 Not Found` if note does not exist.\n\n### Authentication Endpoints (Stretch Goal)\n-   **`POST /api/v1/register`**\n    -   **Description:** Register a new user.\n    -   **Request Body:** `{ \"username\": \"string\", \"password\": \"string\" }`\n    -   **Response:** `201 Created` or `400 Bad Request` (e.g., username taken).\n\n-   **`POST /api/v1/login`**\n    -   **Description:** Authenticate a user and provide an access token.\n    -   **Request Body:** `{ \"username\": \"string\", \"password\": \"string\" }`\n    -   **Response:** `200 OK` with `{ \"access_token\": \"jwt_token\" }` or `401 Unauthorized`.\n\n## Security Architecture\n\n-   **Input Validation & Sanitization:** All user inputs (note titles, content) will be validated and sanitized on both the frontend (Angular forms) and backend (Flask/Python) to prevent common vulnerabilities like Cross-Site Scripting (XSS) and SQL injection.\n-   **HTTPS Enforcement:** All communication between the frontend and backend will be secured using HTTPS to encrypt data in transit.\n-   **Password Hashing (if authentication implemented):** User passwords will never be stored in plaintext. Industry-standard hashing algorithms (e.g., bcrypt) with appropriate salts will be used to store password hashes.\n-   **Authentication (JWT/Session - Stretch Goal):** If user authentication is implemented, JSON Web Tokens (JWT) or secure session management will be used to verify user identity for protected resources. Tokens will be transmitted via secure headers.\n-   **Error Handling:** Generic error messages will be provided to avoid leaking sensitive system information to clients.\n\n## Scalability Considerations\n\n-   **Stateless Backend:** The Flask API will be designed to be stateless, meaning no session data is stored on the server. This allows for easy horizontal scaling by simply adding more instances of the API server behind a load balancer.\n-   **Modular Frontend:** Angular's modular structure and lazy loading capabilities ensure that only necessary code is loaded, improving initial load times and overall performance, which is crucial for perceived scalability.\n-   **Database Indexing:** Appropriate indexes will be created on frequently queried columns (e.g., `id`, `userId`, `createdAt` in the `Notes` table) to optimize database read performance.\n-   **Containerization (Docker):** Packaging the frontend and backend into Docker containers facilitates consistent deployment and orchestration, enabling easy scaling with tools like Kubernetes or Docker Swarm in more complex scenarios.\n-   **Future Caching:** For higher read loads, a caching layer (e.g., Redis) can be introduced for frequently accessed notes or lists.\n-   **Cloud-Native Deployment:** The architecture is designed to be deployed on cloud platforms, leveraging their autoscaling features for both compute and database resources.\n",
  "tech_stack": "\n\n# Technology Stack Document Update - Simple Notes Taking App\nGenerated: 2025-10-09T05:05:00Z\n\n## Frontend Technologies\n-   **Framework:** Angular (v16+, leveraging the base project's foundation)\n-   **Styling:** Clarity Design System (for UI components and consistent look-and-feel)\n-   **State Management:** Angular Services with RxJS Observables (for managing application state and API responses)\n-   **Routing:** Angular Router (for client-side navigation)\n\n## Backend Technologies\n-   **Language:** Python (v3.9+)\n-   **Framework:** Flask (v2.x) - Lightweight and flexible for building RESTful APIs\n-   **ORM:** SQLAlchemy (v1.4+) with Alembic (for database migrations) - Robust ORM for Python, suitable for PostgreSQL\n-   **API:** RESTful API (JSON-based communication)\n-   **Authentication (Optional):** Flask-JWT-Extended (for token-based authentication)\n\n## Database Technologies\n-   **Primary Database:** PostgreSQL (v14+) - Robust, open-source relational database for production.\n-   **Development Database:** SQLite (file-based) - For local development and testing, requiring no separate server setup.\n-   **Caching:** Not in initial scope. (Future consideration: Redis for distributed caching).\n\n## Infrastructure\n-   **Containerization:** Docker (for consistent development, testing, and deployment environments for both frontend and backend).\n-   **Deployment:** Docker Compose (for local multi-container setup), Cloud platform specific services (e.g., AWS ECS/EC2, Heroku, Azure App Services) for production.\n-   **Hosting:** \n    -   **Frontend:** Static site hosting (e.g., AWS S3 + CloudFront, Netlify, Vercel).\n    -   **Backend:** Container orchestration (e.g., AWS ECS, Azure Container Instances, Heroku Dynos).\n\n## Development Tools\n-   **Version Control:** Git (GitHub/GitLab/Bitbucket)\n-   **Code Editor:** Visual Studio Code (with Angular, Python, Docker extensions)\n-   **Package Managers:** npm/Yarn (Frontend), pip (Backend)\n-   **Testing:**\n    -   **Frontend:** Karma, Jasmine (Unit Testing); Protractor/Cypress (E2E Testing - if required).\n    -   **Backend:** Pytest (Unit/Integration Testing).\n-   **CI/CD:** GitHub Actions (for automated builds, tests, and deployments).\n-   **API Testing:** Postman/Insomnia\n-   **Linting/Formatting:** ESLint/Prettier (Frontend), Black/Flake8 (Backend)\n"
}
```

## Base Agent Prompt Reference

This agent is based on the standard io8architect agent with project-specific customizations above.
Refer to the base io8architect agent prompt for general principles and workflow instructions.
