chore: moving towards agentic development

docs/ARCHITECTURE.md

@@ -0,0 +1,92 @@
+# Architecture
+
+## Backend
+
+```txt
+backend/
+├─ Socialize.slnx
+├─ src/Socialize.Api/
+│  ├─ Common/
+│  ├─ Data/
+│  ├─ Infrastructure/
+│  ├─ Migrations/
+│  ├─ Modules/
+│  └─ Program.cs
+└─ tests/Socialize.Tests/
+```
+
+The backend is one API project plus one test project.
+
+The original bootstrap scaffold uses `Endpoints/<Feature>` and `Contracts/<Feature>` for a minimal API. Socialize already uses FastEndpoints modules, so current backend feature code stays under `Modules/<Feature>` until a task intentionally changes that pattern.
+
+## Backend Composition
+
+Entry point:
+
+```txt
+backend/src/Socialize.Api/Program.cs
+```
+
+Composition registers:
+
+- web services and auth in `DependencyInjection.cs`
+- infrastructure in `Infrastructure/DependencyInjection.cs`
+- domain modules for Identity, Workspaces, Clients, Projects, ContentItems, Assets, Comments, Approvals, and Notifications
+
+## Data Ownership
+
+The current implementation uses a shared `AppDbContext` in:
+
+```txt
+backend/src/Socialize.Api/Data/AppDbContext.cs
+```
+
+Workflow data is organized by module folders. Do not couple unrelated modules through ad hoc service calls; keep ownership boundaries explicit.
+
+## Frontend
+
+```txt
+frontend/src/
+├─ api/
+├─ app/
+├─ components/
+├─ features/
+├─ layouts/
+├─ pages/
+├─ plugins/
+├─ router/
+├─ stores/
+└─ views/
+```
+
+The generated scaffold expects `app/`, `features/`, `pages/`, `router/`, `stores/`, and `api/`. Socialize currently has substantial existing code under `views/`, `stores/`, and `plugins/`. New isolated feature work should prefer `features/<feature>/`; existing screens should be migrated only by explicit task.
+
+## API Contract
+
+The backend exposes NSwag OpenAPI in development at:
+
+```txt
+http://localhost:5080/swagger/v1/swagger.json
+```
+
+The frontend updates its OpenAPI model with:
+
+```bash
+./scripts/update-openapi.sh
+```
+
+Contract flow:
+
+```txt
+Backend contracts -> OpenAPI -> frontend TypeScript types
+```
+
+## Deployment Shape
+
+Docker Compose runs:
+
+- `postgres`
+- `api`
+- `web`
+
+Caddy serves the frontend and reverse-proxies API paths to the backend.