feat: Initial commit of backend services and AGENTS.md

AGENTS.md

@@ -0,0 +1,67 @@
+# Adopt-a-Street Agents
+
+This document outlines the various agents (user roles and automated systems) within the Adopt-a-Street application, their capabilities, and how they interact with the platform.
+
+## User Agents
+
+### 1. Regular User
+
+Regular users are the primary actors in the Adopt-a-Street ecosystem. They are community members who volunteer to maintain and improve their local streets.
+
+**Capabilities:**
+
+*   **Authentication:** Register for a new account, log in, and log out.
+*   **Street Adoption:** View available streets on a map and adopt one or more streets to care for.
+*   **Task Management:** View and complete maintenance tasks associated with their adopted streets (e.g., trash pickup, graffiti removal).
+*   **Social Feed:** Share updates and photos of their work, view posts from other users, and engage with the community.
+*   **Events:** Participate in community cleanup events and other local initiatives.
+*   **Rewards:** Earn points and badges for completing tasks and participating in events, which can be redeemed for rewards.
+*   **Profile Management:** View their profile, including adopted streets, completed tasks, points, and badges.
+
+### 2. Premium User
+
+Premium users have all the capabilities of regular users, with potential access to additional features and benefits.
+
+**Capabilities:**
+
+*   All capabilities of a Regular User.
+*   **Premium Features:** Access to exclusive rewards, advanced analytics, or other premium features (as defined by the application).
+
+## Automated Agents
+
+### 1. AI Agent
+
+The AI agent provides intelligent features and support to users, helping to streamline the street adoption process and enhance the user experience.
+
+**Functionality:**
+
+*   **Task Suggestions:** Recommends maintenance tasks based on street conditions, user activity, and other data.
+*   **Community Insights:** Provides analytics and insights into community engagement and environmental impact.
+*   **Gamification:** Manages the points, badges, and rewards system to encourage user participation.
+
+## System Architecture
+
+The Adopt-a-Street application is a full-stack web application with a React frontend and a Node.js/Express backend.
+
+### Frontend Components
+
+*   **`MapView`:** Displays an interactive map of streets, allowing users to view available streets and adopt them.
+*   **`TaskList`:** Lists the maintenance tasks for a user's adopted streets.
+*   **`SocialFeed`:** A social media-style feed for users to share updates and connect with others.
+*   **`Profile`:** Displays user information, including adopted streets, points, and badges.
+*   **`Events`:** Shows upcoming community events and allows users to RSVP.
+*   **`Rewards`:** A marketplace where users can redeem points for rewards.
+*   **`Login` and `Register`:** User authentication components.
+*   **`AuthContext`:** Manages user authentication state throughout the application.
+
+### Backend API Endpoints
+
+*   `/api/auth`: User registration and login.
+*   `/api/streets`: Get street data and adopt streets.
+*   `/api/tasks`: Manage maintenance tasks.
+*   `/api/posts`: Create and view posts in the social feed.
+*   `/api/events`: Manage community events.
+*   `/api/rewards`: Manage rewards and user points.
+*   `/api/reports`: User-submitted reports on street conditions.
+*   `/api/ai`: AI-powered suggestions and insights.
+*   `/api/payments`: Handle premium subscriptions and other payments.