# io8 System Architect Agent - Customized for This Project

## Project-Specific Instructions


# Architecture Document Update: Messaging App
Generated: 2025-10-10T[timestamp]

## System Overview
The Messaging App extends the existing Angular Clarity Boilerplate frontend with a new, dedicated backend. The architecture is a **Client-Server model** with a robust **Real-time Communication Layer**. The Angular frontend provides the user interface for authentication, user management, and interactive chat. The backend, composed of several specialized services, handles business logic, data persistence, and real-time message exchange via WebSockets. This separation ensures scalability, maintainability, and allows independent evolution of frontend and backend components. The system prioritizes low-latency message delivery, secure communication, and horizontal scalability to accommodate a growing user base, as derived from `analysis_document.md` and `requirements_document.md`.

## Architecture Pattern
The core architecture pattern for the Messaging App is a **Hybrid Client-Server / Layered Architecture** with a strong emphasis on a **Publish-Subscribe (Pub/Sub) pattern** for real-time messaging:

1.  **Client-Server:** The Angular frontend acts as the client, communicating with the backend API servers.
2.  **Layered Backend:** The backend is designed with distinct layers:
    *   **Presentation/API Gateway:** Handles incoming HTTP/WebSocket requests, routing, and potentially authentication pre-checks.
    *   **Application Services:** Implements core business logic for user management, conversations, and messages.
    *   **Real-time Communication Layer:** Dedicated WebSocket server(s) manage persistent connections and message broadcasting.
    *   **Data Access Layer:** Interfaces with the database for CRUD operations.
3.  **Publish-Subscribe (for Real-time):** A message broker (e.g., Redis Pub/Sub) will be used to facilitate real-time message exchange between backend services (e.g., a message service publishing new messages, and multiple WebSocket servers subscribing to these messages to fan-out to connected clients). This pattern is crucial for horizontal scaling of WebSocket servers, addressing NFR-003 (Scalability) from `requirements_document.md`.

## Component Design
The system is composed of the following key components, aligning with `analysis_document.md`'s architectural components and `requirements_document.md`'s data and interface requirements:

### 1. Frontend (Angular Clarity Application)
*   **Purpose:** User interface for interaction, leveraging the existing Angular Clarity boilerplate.
*   **Modules:**
    *   `AuthModule`: Handles user registration, login, and session management (communicates with Backend Auth Service).
    *   `UserModule`: Manages user profiles, search, and presence display (communicates with Backend User Service).
    *   `ChatModule`: Core messaging functionality, including conversation list, chat window, message input, and real-time message display. (Communicates with Backend Conversation, Message, and WebSocket Services).
    *   `CoreModule` & `SharedModule`: As per boilerplate, for singleton services (e.g., HTTP interceptors, WebSocket client) and reusable UI components.
*   **Key Features:** Responsive UI (NFR-007), Real-time message rendering, User presence display.

### 2. Backend Services
Designed as a set of loosely coupled services, potentially evolving into microservices, to manage core functionalities.

*   **2.1. Authentication Service (REST API):**
    *   **Purpose:** Manages user authentication and authorization (FR-001, FR-002, NFR-003, NFR-004).
    *   **Responsibilities:** User registration, login, JWT token issuance, validation, and refresh. Password hashing.
    *   **Interaction:** Exposes REST endpoints (`POST /api/auth/register`, `POST /api/auth/login`) as per `requirements_document.md`.

*   **2.2. User Service (REST API):**
    *   **Purpose:** Manages user profiles and provides user search capabilities (FR-003, FR-005).
    *   **Responsibilities:** Store and retrieve user profile information, handle profile updates, provide search functionality for other users.
    *   **Interaction:** Exposes REST endpoints (`GET /api/users/me`, `PUT /api/users/me`, `GET /api/users/search`).

*   **2.3. Conversation Service (REST API):**
    *   **Purpose:** Manages the creation and retrieval of 1:1 and group conversations (FR-009).
    *   **Responsibilities:** Create new conversations, manage participants (FR-010), retrieve lists of conversations a user is part of.
    *   **Interaction:** Exposes REST endpoints (`GET /api/conversations`, `POST /api/conversations/one-to-one`, `POST /api/conversations/group`).

*   **2.4. Message Service (Internal & REST API):**
    *   **Purpose:** Persists messages and retrieves chat history (FR-008).
    *   **Responsibilities:** Store incoming messages from the WebSocket Service, retrieve paginated message history for conversations.
    *   **Interaction:** Exposes REST endpoint (`GET /api/conversations/{id}/messages`) for history, and an internal API for the WebSocket Service to persist new messages.

*   **2.5. Real-time WebSocket Service:**
    *   **Purpose:** Manages persistent WebSocket connections, handles real-time message delivery, and user presence updates (FR-006, FR-007, FR-009, NFR-001, NFR-007).
    *   **Responsibilities:** Authenticate WebSocket connections using JWT, receive messages from clients, persist them via Message Service, broadcast messages to relevant recipients, manage user online/offline status, propagate status updates via Redis Pub/Sub.
    *   **Interaction:** Exposes a WSS endpoint (`wss://api.yourdomain.com/ws/chat`), integrates with Redis for Pub/Sub and presence, and with Message Service for persistence.

### 3. Database
*   **Purpose:** Persistent storage for all application data, adhering to `requirements_document.md`'s Data Requirements.
*   **Key Entities:** `User`, `Conversation`, `ConversationParticipant`, `Message` (as defined in `requirements_document.md`).
*   **Relationships:** One-to-many and many-to-many relationships modeled for users, conversations, and messages.

### 4. Caching / Message Broker (Redis)
*   **Purpose:** Enhances real-time performance, manages presence, and facilitates inter-service communication for WebSockets.
*   **Responsibilities:** Store user presence status (online/offline), act as a Pub/Sub broker for real-time message distribution across multiple WebSocket service instances, potentially caching frequently accessed data (e.g., user profiles).

### 5. Object Storage (e.g., AWS S3 - for Phase 2 Media Sharing)
*   **Purpose:** Store media files (images, documents) for sharing (FR-017, FR-018).
*   **Responsibilities:** Provides scalable and secure storage for user-uploaded content. The Message Service will store references (URLs) to these objects.

## Data Flow

1.  **User Authentication & Profile Management:**
    *   Frontend (Angular) sends `POST /api/auth/register` or `POST /api/auth/login` to Backend Auth Service.
    *   Auth Service interacts with Database to create/verify user credentials. Issues JWT.
    *   Frontend uses JWT for subsequent requests to Backend User Service (e.g., `GET /api/users/me`, `PUT /api/users/me`), which then interacts with Database.

2.  **Real-time Messaging (1:1 & Group Chat):**
    *   After authentication, Frontend (Angular) establishes a secure WebSocket connection (`wss://api.yourdomain.com/ws/chat`) to the Backend WebSocket Service, providing JWT for authorization.
    *   **Sending a Message:** Frontend sends `send_message` event over WebSocket to Backend WebSocket Service. WebSocket Service persists message via Message Service (to Database). WebSocket Service then publishes the new message to a Redis Pub/Sub channel.
    *   **Receiving a Message:** Other instances of Backend WebSocket Service (subscribed to Redis Pub/Sub) receive the published message. They identify relevant connected clients and fan out the `new_message` event over their respective WebSockets to the recipients' Frontends.
    *   **Message History:** Frontend retrieves older messages via `GET /api/conversations/{id}/messages` from Backend Message Service (REST API), which queries the Database.

3.  **User Presence:**
    *   Frontend sends `user_online`/`user_offline` events (or inferred from WebSocket connection status) to Backend WebSocket Service.
    *   WebSocket Service updates user status in Redis (for fast retrieval across instances) and potentially Database.
    *   Status changes are published via Redis Pub/Sub to inform other connected users.

## API Design
As detailed in `requirements_document.md` (Interface Requirements):

*   **RESTful API:** For stateless operations such as user registration, login, profile management, and fetching historical data (user lists, chat history).
    *   Endpoints like `/api/auth/register`, `/api/auth/login`, `/api/users/me`, `/api/conversations`, `/api/conversations/{id}/messages` will be implemented.
    *   Communication will be JSON over HTTPS.
*   **WebSocket API:** For real-time, bidirectional communication.
    *   A single `wss://api.yourdomain.com/ws/chat` endpoint will be used.
    *   Events like `send_message`, `new_message`, `user_status_update`, `typing_indicator` will be exchanged.
    *   Payloads will be JSON.

## Security Architecture
Addressing NFR-002 (Security) from `requirements_document.md`:

*   **Authentication:**
    *   **JWT (JSON Web Tokens):** Used for authenticating REST API requests and authorizing WebSocket connections. Tokens will have short lifespans with a refresh token mechanism.
    *   **Password Hashing:** User passwords will be hashed and salted using strong, industry-standard algorithms (e.g., bcrypt) before storage in the database.
*   **Authorization:**
    *   **Role-Based Access Control (RBAC):** Implemented at the backend for sensitive actions (e.g., group administration (FR-011), accessing message history (NFR-004)).
    *   **Scope-Based Authorization:** JWTs will contain claims to define the scope of a user's access.
*   **Data Encryption:**
    *   **In-transit:** All HTTP and WebSocket communication will be encrypted using **TLS/SSL (HTTPS/WSS)** (NFR-005).
    *   **At-rest:** Database encryption and secure storage practices will be applied, especially for media files (if applicable, using encrypted storage services).
*   **Input Validation:** Comprehensive input validation will be implemented on all backend API endpoints to prevent common vulnerabilities such as XSS, SQL injection, and buffer overflows (NFR-002).
*   **Session Management:** Secure session management for JWTs, including proper storage (e.g., HttpOnly cookies) and invalidation on logout.

## Scalability Considerations
Addressing NFR-003 (Scalability) from `requirements_document.md`:

*   **Horizontal Scaling:**
    *   **Stateless Services:** Backend API services will be designed as stateless entities, allowing them to be horizontally scaled by adding more instances behind a load balancer.
    *   **WebSocket Service Scaling:** Multiple instances of the WebSocket Service can run concurrently. Redis Pub/Sub acts as a backbone to distribute messages across these instances, ensuring all clients receive messages regardless of which WebSocket server they are connected to.
*   **Load Balancing:** A load balancer (e.g., Nginx, or cloud-native solutions) will distribute incoming HTTP and WebSocket traffic across multiple backend service instances.
*   **Database Scalability:**
    *   **Read Replicas:** PostgreSQL can be configured with read replicas to offload read-heavy operations (e.g., fetching chat history) from the primary database instance.
    *   **Connection Pooling:** Efficient database connection pooling will be used by backend services to manage database load.
    *   **Sharding (Future):** For extremely high message volumes, message data might be sharded across multiple database instances based on conversation ID or user ID.
*   **Caching:** Redis will be used for caching frequently accessed data (e.g., user profiles, online status) to reduce database load and improve response times.
*   **Asynchronous Processing:** Backend operations, especially for media sharing (Phase 2), will leverage asynchronous processing to avoid blocking the main request/response cycle, potentially using background task queues (e.g., Celery with Redis).



# Technology Stack Document Update: Messaging App
Generated: 2025-10-10T[timestamp]

## Frontend Technologies
-   **Framework:** Angular (v12+), leveraging the existing Angular Clarity Boilerplate structure and tools.
-   **Styling:** VMware Clarity Design System (CSS components and styles).
-   **State Management:** RxJS for reactive programming and managing application state, Angular Services for shared data logic. Potentially NgRx for more complex global state management in later phases if needed.
-   **Real-time Client:** Native WebSocket API through Angular services, potentially using `ngx-web-socket` or a similar wrapper for streamlined integration.

## Backend Technologies
-   **Language:** Python 3.9+ (Chosen for its robust ecosystem, excellent asynchronous capabilities, and developer productivity, making it suitable for a real-time application).
-   **Framework:** FastAPI (High-performance web framework for building APIs with Python 3.7+ based on standard Python type hints. Ideal for RESTful APIs and seamless integration with WebSockets due to its ASGI nature).
-   **API:**
    -   **RESTful API:** Implemented with FastAPI for authentication, user management, and historical data retrieval.
    -   **WebSocket API:** Implemented using FastAPI's built-in Starlette WebSocket capabilities for real-time messaging and presence.
-   **ORM/Database Client:** SQLAlchemy with Alembic for migrations (for PostgreSQL interaction, offering robust ORM capabilities and database schema management).
-   **Password Hashing:** `bcrypt` library.
-   **JWT Handling:** `python-jose` or `PyJWT` for token generation and validation.

## Database Technologies
-   **Primary Database:** PostgreSQL (Chosen for its reliability, advanced features like JSONB, robust transaction support, and strong scalability for relational data. Suitable for storing user, conversation, and message data).
-   **Caching/Message Broker:** Redis (Used for storing user presence data, serving as a Pub/Sub message broker for real-time event distribution across WebSocket instances, and for general-purpose caching).

## Infrastructure
-   **Deployment:**
    -   **Containerization:** Docker (All frontend and backend services will be containerized).
    -   **Orchestration (Local/Dev):** Docker Compose (For defining and running multi-container Docker applications for local development and staging environments).
    -   **Orchestration (Production):** Kubernetes or AWS ECS/Fargate (Future consideration for highly scalable and resilient production deployments, allowing for horizontal scaling of backend and WebSocket services).
-   **Hosting:** Cloud-agnostic design, with potential deployment on AWS, Azure, or GCP. For media storage (Phase 2), cloud-native object storage like AWS S3 or Google Cloud Storage will be utilized.
-   **Reverse Proxy/Load Balancer:** Nginx (To serve the Angular frontend, proxy API requests to backend services, and manage WebSocket connections, handling SSL termination).

## Development Tools
-   **Version Control:** Git (GitHub/GitLab/Bitbucket for repository hosting).
-   **Testing:**
    -   **Frontend:** Jest / Karma & Jasmine (For Angular unit and integration tests).
    -   **Backend:** Pytest (For Python backend unit, integration, and API tests).
-   **CI/CD:** GitHub Actions / GitLab CI / Jenkins (To automate testing, building, and deployment pipelines).
-   **Code Quality:** Prettier, ESLint (Frontend); Black, Flake8 (Backend) for code formatting and linting.
-   **API Documentation:** FastAPI's automatic OpenAPI (Swagger UI/ReDoc) generation for backend API documentation.


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