# io8 System Architect Agent - Customized for This Project

## Project-Specific Instructions


# Architecture Document
Generated: 2025-10-06 07:15:00

## System Overview - Working Notes Application
The "Working Notes Application" is a single-page application (SPA) designed to provide users with a secure and intuitive platform for creating, organizing, and retrieving personal notes. It leverages an existing Angular Clarity Boilerplate for the frontend, ensuring a modern, responsive user interface and a standardized development foundation. The application interacts with a dedicated backend RESTful API responsible for user authentication and all note-related CRUD (Create, Read, Update, Delete) operations, backed by a persistent database.

## Architecture Pattern - Working Notes Application
The application follows a **Client-Server architecture** with a **Single Page Application (SPA)** frontend communicating with a **RESTful API** backend.

### Frontend Architecture (Angular with Clarity)
Building upon the Angular Clarity Boilerplate, the frontend utilizes a modular architecture:
-   **CoreModule:** For singleton services (e.g., `AuthService`, `ErrorHandlingService`), HTTP interceptors, and application-wide components.
-   **SharedModule:** For reusable UI components (e.g., custom card, alert messages, loading spinners) and utility directives/pipes that can be imported into any feature module. These will primarily leverage Clarity Design System components.
-   **Feature Modules:
    -   **AuthModule:** Encapsulates user authentication features (Login, Registration, Password Reset).
    -   **NotesModule:** Manages all note-related functionalities (List, View, Create, Edit, Delete notes).
-   **AppModule:** Orchestrates the root application components and routing.

### Backend Architecture (RESTful API)
A **Monolithic REST API** will be implemented for the initial MVP, providing a unified entry point for all client requests. This approach simplifies deployment and management for the initial phase while allowing for potential future decomposition into microservices if scalability demands grow. The API will be stateless, facilitating horizontal scaling.

## Component Design - Working Notes Application

### Frontend Components (Angular)
-   **AuthModule:
    -   `LoginComponent`: Handles user login.
    -   `RegisterComponent`: Handles new user registration.
    -   `ForgotPasswordComponent`: Initiates password reset flow.
    -   `ResetPasswordComponent`: Allows users to set a new password.
    -   `AuthGuard`: Protects authenticated routes.
    -   `AuthService`: Manages user authentication state, token storage, and API calls to backend auth endpoints.
-   **NotesModule:
    -   `NoteListComponent`: Displays a list of user's notes, potentially with filtering/sorting.
    -   `NoteDetailComponent`: Shows a single note's content, allows editing.
    -   `NoteCreateComponent`: Form for creating a new note.
    -   `NotesService`: Handles API calls for note CRUD operations.
-   **CoreModule:
    -   `HeaderComponent`: Application header (logo, user menu, logout).
    -   `SidebarComponent`: Navigation sidebar (links to notes, settings, etc.).
    -   `HttpInterceptorService`: Centralized error handling and token attachment for API requests.
-   **SharedModule:
    -   Generic UI components built with Clarity (e.g., `ConfirmModalComponent`, `LoadingSpinnerComponent`).

### Backend Services/Controllers
-   **`UserController`:** Handles user registration, login, password management, and user profile operations.
-   **`NoteController`:** Manages CRUD operations for notes, ensuring notes are associated with the correct user.
-   **`AuthService` (Backend):** Responsible for JWT generation, validation, and managing token blacklists (if implemented).

## Data Architecture - Working Notes Application

### Database Schema
A relational database will store user and note data.

-   **`Users` Table:
    -   `id` (PK, UUID/Integer)
    -   `username` (VARCHAR, UNIQUE)
    -   `email` (VARCHAR, UNIQUE)
    -   `password_hash` (VARCHAR)
    -   `created_at` (TIMESTAMP)
    -   `updated_at` (TIMESTAMP)
-   **`Notes` Table:
    -   `id` (PK, UUID/Integer)
    -   `user_id` (FK to Users.id)
    -   `title` (VARCHAR)
    -   `content` (TEXT)
    -   `tags` (JSONB/VARCHAR array, optional for future search/filter)
    -   `created_at` (TIMESTAMP)
    -   `updated_at` (TIMESTAMP)

### Data Flow
1.  Frontend sends API requests (JSON) to the Backend REST API via Angular's `HttpClient`.
2.  Backend receives requests, processes business logic, and interacts with the database using an ORM (Object-Relational Mapper).
3.  Database stores/retrieves data.
4.  Backend returns API responses (JSON) to the Frontend.

## API Design - Working Notes Application
A RESTful API will be exposed by the backend, adhering to standard HTTP methods and status codes. All endpoints will be prefixed with `/api`.

### Authentication Endpoints (`/api/auth`)
-   `POST /api/auth/register`: Register a new user.
    -   Request: `{ username, email, password }`
    -   Response: `{ userId, message }`
-   `POST /api/auth/login`: Authenticate user and issue JWT.
    -   Request: `{ username/email, password }`
    -   Response: `{ accessToken, expiresIn }`
-   `POST /api/auth/forgot-password`: Initiate password reset.
    -   Request: `{ email }`
    -   Response: `{ message }`
-   `POST /api/auth/reset-password`: Set new password using a token.
    -   Request: `{ token, newPassword }`
    -   Response: `{ message }`

### Note Management Endpoints (`/api/notes`) - Requires Authentication
-   `GET /api/notes`: Retrieve all notes for the authenticated user.
    -   Response: `[ { id, title, content, tags, createdAt, updatedAt }, ... ]`
-   `GET /api/notes/:id`: Retrieve a specific note by ID.
    -   Response: `{ id, title, content, tags, createdAt, updatedAt }`
-   `POST /api/notes`: Create a new note.
    -   Request: `{ title, content, tags }`
    -   Response: `{ id, title, content, tags, createdAt, updatedAt }` (new note object)
-   `PUT /api/notes/:id`: Update an existing note.
    -   Request: `{ title, content, tags }` (partial or full update)
    -   Response: `{ id, title, content, tags, createdAt, updatedAt }` (updated note object)
-   `DELETE /api/notes/:id`: Delete a specific note.
    -   Response: `{ message }`

## Security Architecture - Working Notes Application
-   **Authentication (JWT):** Users authenticate once to receive a JSON Web Token (JWT). This token is stored securely (e.g., in `localStorage` or `sessionStorage` on frontend) and sent with every subsequent request in the `Authorization: Bearer <token>` header. The backend validates the token for authenticity and expiration.
-   **Authorization:** The backend verifies that the authenticated user (identified by the JWT) has the necessary permissions to perform actions on specific resources (e.g., a user can only view/edit/delete their own notes).
-   **Password Hashing:** User passwords are never stored in plain text. A strong, one-way cryptographic hashing algorithm (e.g., bcrypt) with a salt will be used before storing passwords in the database.
-   **HTTPS:** All communication between the frontend and backend will be encrypted using HTTPS to prevent eavesdropping and data tampering.
-   **Input Validation:** Strict server-side input validation will be applied to all incoming API requests to prevent common vulnerabilities like SQL injection, XSS, and buffer overflows.
-   **CORS (Cross-Origin Resource Sharing):** Properly configured on the backend to allow requests only from the Angular application's domain.
-   **Rate Limiting:** Implement rate limiting on authentication endpoints (login, register, forgot password) to mitigate brute-force attacks.

## Scalability Considerations - Working Notes Application
-   **Frontend:
    -   **Lazy Loading:** Feature modules (Auth, Notes) will be lazy-loaded to reduce initial bundle size and improve load times.
    -   **Clarity Performance:** Clarity components are designed for performance; proper usage will be encouraged.
-   **Backend:
    -   **Stateless API:** The REST API is designed to be stateless, allowing for easy horizontal scaling by adding more backend instances behind a load balancer.
    -   **Database Scaling:** For initial MVP, a single PostgreSQL instance is sufficient. Future scaling could involve read replicas, sharding, or moving to a managed database service.
    -   **Caching:** Introduction of caching layers (e.g., Redis) for frequently accessed, immutable data (e.g., configuration settings) or user-specific notes to reduce database load, if performance becomes a bottleneck.
-   **Infrastructure:** Containerization with Docker provides environment consistency and facilitates deployment to various cloud platforms that support orchestration (e.g., Kubernetes).


# Technology Stack Document
Generated: 2025-10-06 07:15:00

## Frontend Technologies - Working Notes Application
-   **Framework:** Angular (latest stable version, inheriting from boilerplate)
-   **Styling:** VMware Clarity Design System, SCSS (for custom styles)
-   **State Management:** Angular Services with RxJS (Observable-based state management)
-   **HTTP Client:** Angular's `HttpClient` Module

## Backend Technologies - Working Notes Application
-   **Language:** Python
-   **Framework:** Flask (lightweight, flexible, excellent for REST APIs)
-   **API:** RESTful API
-   **ORM:** SQLAlchemy (Python ORM for database interaction)
-   **Authentication Library:** PyJWT (for JSON Web Token handling), Flask-Bcrypt (for password hashing)

## Database Technologies - Working Notes Application
-   **Primary Database:** PostgreSQL (robust, open-source relational database for production)
-   **Development Database:** SQLite (for local development and testing simplicity)
-   **Caching:** Redis (optional, for future performance optimizations like session caching or frequently accessed data)

## Infrastructure - Working Notes Application
-   **Deployment:** Docker (containerization for both frontend and backend)
-   **Orchestration:** Docker Compose (for local multi-container development), Kubernetes (future consideration for production orchestration)
-   **Hosting:** AWS (e.g., EC2 for backend, S3 for frontend static assets, RDS for PostgreSQL) or similar cloud provider.
-   **Web Server (Frontend):** Nginx (for serving Angular static files)
-   **Web Server (Backend):** Gunicorn/uWSGI (production WSGI HTTP server for Flask)

## Development Tools - Working Notes Application
-   **Version Control:** Git (GitHub/GitLab/Bitbucket)
-   **Frontend Testing:** Jasmine, Karma (unit testing), Cypress (end-to-end testing)
-   **Backend Testing:** Pytest (unit and integration testing for Python)
-   **CI/CD:** GitHub Actions (automated build, test, and deployment pipelines)
-   **Code Quality:** ESLint, Prettier (Frontend), Black, Flake8 (Backend)
-   **API Documentation:** OpenAPI/Swagger UI (generated from backend code or manually defined)


## 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.
