feat: add City10 platform with Laravel 13, AI agents, 3D viewer, and LGPD compliance

Initial commit of the complete City10 virtual city simulation platform.

Backend (Laravel 13):
- REST API with Sanctum tokens and session-based web authentication
- Role-based access control (admin/user) with middleware protection
- AI agent CRUD with OpenRouter.ai integration restricted to free models
- Store management with 3D coordinates and AI shopkeeper assignment
- Versioned legal documents (Terms, Privacy, Cookies) with LGPD audit trail
- Math CAPTCHA on public forms and multi-language support (pt_BR, en, es)

Frontend:
- Responsive Blade templates with Tailwind CSS v4
- Three.js 3D city viewer with SSE chat streaming to AI agents
- Admin panel for store and user administration

Infrastructure:
- MariaDB/MySQL database with comprehensive migrations
- Database seeders for demo content and test accounts
- PHPUnit test suite and Laravel Pint code styling
- Vite build configuration with hot reload

app/Models/AiAgent.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\AiAgentFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * Autonomous AI agent entity.
+ *
+ * Drives NPCs and managers of the virtual city through the OpenRouter.ai
+ * API. Only allow-listed free models may be selected by administrators.
+ */
+#[Fillable([
+    'name', 'type', 'model', 'system_prompt', 'current_goal', 'last_decision',
+    'status', 'error_count', 'pos_x', 'pos_y', 'pos_z', 'rotation_y', 'last_think_at',
+])]
+class AiAgent extends Model
+{
+    /** @use HasFactory<AiAgentFactory> */
+    use HasFactory;
+
+    /**
+     * Attributes that should be cast to native types.
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'last_decision' => 'array',
+            'last_think_at' => 'datetime',
+            'pos_x' => 'float',
+            'pos_y' => 'float',
+            'pos_z' => 'float',
+            'rotation_y' => 'float',
+            'error_count' => 'integer',
+        ];
+    }
+
+    /**
+     * Stores managed by this agent (shopkeepers, mayors, etc.).
+     *
+     * @return HasMany<Store, $this>
+     */
+    public function stores(): HasMany
+    {
+        return $this->hasMany(Store::class, 'agent_id');
+    }
+}

app/Models/LegalDocument.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+
+/**
+ * Versioned legal document (Terms of Use, Privacy Policy, Cookie Policy).
+ *
+ * Bodies are stored per language so that the UI can render the version
+ * matching the user's selected locale at acceptance time.
+ */
+#[Fillable(['type', 'version', 'title', 'body', 'is_current', 'published_at'])]
+class LegalDocument extends Model
+{
+    /**
+     * Document type: Terms of Use.
+     *
+     * @var string
+     */
+    public const TYPE_TERMS = 'terms';
+
+    /**
+     * Document type: Privacy Policy (LGPD).
+     *
+     * @var string
+     */
+    public const TYPE_PRIVACY = 'privacy';
+
+    /**
+     * Document type: Cookie Policy.
+     *
+     * @var string
+     */
+    public const TYPE_COOKIES = 'cookies';
+
+    /**
+     * Attributes that should be cast to native types.
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'title' => 'array',
+            'body' => 'array',
+            'is_current' => 'boolean',
+            'published_at' => 'datetime',
+        ];
+    }
+
+    /**
+     * Users that accepted this document version.
+     *
+     * @return BelongsToMany<User, $this>
+     */
+    public function users(): BelongsToMany
+    {
+        return $this->belongsToMany(User::class, 'user_consents')
+            ->withPivot(['accepted_at', 'ip_address', 'user_agent', 'source'])
+            ->withTimestamps();
+    }
+}

app/Models/Store.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\StoreFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * Physical store placed inside the 3D city.
+ *
+ * Each store has an exact (x, y, z) world coordinate, footprint dimensions
+ * and an optional AI shopkeeper agent controlling its commercial behaviour.
+ */
+#[Fillable([
+    'name', 'description', 'type', 'owner_id', 'agent_id',
+    'pos_x', 'pos_y', 'pos_z', 'width', 'height', 'depth',
+    'is_open', 'revenue',
+])]
+class Store extends Model
+{
+    /** @use HasFactory<StoreFactory> */
+    use HasFactory;
+
+    /**
+     * Owner (shopkeeper) account.
+     *
+     * @return BelongsTo<User, $this>
+     */
+    public function owner(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'owner_id');
+    }
+
+    /**
+     * AI agent controlling the store, when assigned.
+     *
+     * @return BelongsTo<AiAgent, $this>
+     */
+    public function agent(): BelongsTo
+    {
+        return $this->belongsTo(AiAgent::class, 'agent_id');
+    }
+
+    /**
+     * Get the attributes that should be cast to native types.
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'pos_x' => 'float',
+            'pos_y' => 'float',
+            'pos_z' => 'float',
+            'width' => 'float',
+            'height' => 'float',
+            'depth' => 'float',
+            'revenue' => 'float',
+            'is_open' => 'boolean',
+        ];
+    }
+}

app/Models/User.php

@@ -0,0 +1,113 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\UserFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Attributes\Hidden;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Foundation\Auth\User as Authenticatable;
+use Illuminate\Notifications\Notifiable;
+use Laravel\Sanctum\HasApiTokens;
+
+/**
+ * Application user entity.
+ *
+ * Supports role based access control (admin/user) and records the
+ * acceptance of versioned legal documents (Terms, Privacy, Cookies)
+ * required by the Brazilian LGPD.
+ */
+#[Fillable(['name', 'email', 'password', 'role', 'locale', 'is_active'])]
+#[Hidden(['password', 'remember_token'])]
+class User extends Authenticatable
+{
+    /** @use HasFactory<UserFactory> */
+    use HasApiTokens, HasFactory, Notifiable;
+
+    /**
+     * Role granted to platform administrators.
+     *
+     * @var string
+     */
+    public const ROLE_ADMIN = 'admin';
+
+    /**
+     * Role granted to regular citizens of the virtual city.
+     *
+     * @var string
+     */
+    public const ROLE_USER = 'user';
+
+    /**
+     * Stores owned by this user.
+     *
+     * @return HasMany<Store, $this>
+     */
+    public function stores(): HasMany
+    {
+        return $this->hasMany(Store::class, 'owner_id');
+    }
+
+    /**
+     * Legal consents recorded for this user.
+     *
+     * @return HasMany<UserConsent, $this>
+     */
+    public function consents(): HasMany
+    {
+        return $this->hasMany(UserConsent::class);
+    }
+
+    /**
+     * Legal documents this user has accepted.
+     *
+     * @return BelongsToMany<LegalDocument, $this>
+     */
+    public function acceptedDocuments(): BelongsToMany
+    {
+        return $this->belongsToMany(LegalDocument::class, 'user_consents')
+            ->withPivot(['accepted_at', 'ip_address', 'user_agent', 'source'])
+            ->withTimestamps();
+    }
+
+    /**
+     * Determine whether the user holds administrator privileges.
+     */
+    public function isAdmin(): bool
+    {
+        return $this->role === self::ROLE_ADMIN;
+    }
+
+    /**
+     * Check whether the user accepted every current legal document version.
+     */
+    public function hasAcceptedCurrentTerms(): bool
+    {
+        $currentIds = LegalDocument::query()->where('is_current', true)->pluck('id');
+
+        if ($currentIds->isEmpty()) {
+            return true;
+        }
+
+        $acceptedIds = $this->consents()->pluck('legal_document_id');
+
+        return $currentIds->diff($acceptedIds)->isEmpty();
+    }
+
+    /**
+     * Get the attributes that should be cast.
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'email_verified_at' => 'datetime',
+            'last_login_at' => 'datetime',
+            'password' => 'hashed',
+            'is_active' => 'boolean',
+        ];
+    }
+}

app/Models/UserConsent.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * Immutable audit record of a user consent event.
+ *
+ * Captures which legal document version was accepted, when, from which IP
+ * and through which channel, enabling full LGPD accountability.
+ */
+#[Fillable(['user_id', 'legal_document_id', 'accepted_at', 'ip_address', 'user_agent', 'source'])]
+class UserConsent extends Model
+{
+    /**
+     * Attributes that should be cast to native types.
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'accepted_at' => 'datetime',
+        ];
+    }
+
+    /**
+     * User that granted the consent.
+     *
+     * @return BelongsTo<User, $this>
+     */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    /**
+     * Legal document version that was accepted.
+     *
+     * @return BelongsTo<LegalDocument, $this>
+     */
+    public function document(): BelongsTo
+    {
+        return $this->belongsTo(LegalDocument::class, 'legal_document_id');
+    }
+}